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In most books, the I, or first person, 1s omitted; in this tt will be 
retained...We commonly do not remember that it 1s, after all, 
always the first person that is speaking. I should not talk so 
much about myself if there were anybody else whom I knew as 
well. Unfortunately, Iam confined to this theme by the narrow- 
ness of my experience. 


—Henry David Thoreau, Walden 


Before starting into the general introduction of this book, a brief com- 
ment on style isin order. Because there were to be three authors of this 
book, there was some difficulty in deciding how to keep writing style 
consistent across chapters. Finally, for the purposes of expedience, it 
was decided that authorial subjects would take the first person plural 
form and that they would use second person address. In other words, 
we decided that we would call ourselves we and refer to you as you. It 
was that or write the whole book in passive voice. 


So while the subject of this 
book 1s using OS/2 to 
program with the “NetWare 
Client SDK for C,” the 
information presented is 
applicable to anyone 
programming in DOS 

or Windows. 


So while at first it may seem a bit odd to read that “we” suggest that 
“you” do this or that, it is a convention that has made this book much 
more readable. And we'll leave it to you to decide when we are employ- 
ing the royal we instead of the plural we. 


NetWare APls 


As the authors of this book we purport to know one thing—NetWare 
APIs. Whether they have been called Application Program Interfaces 
(APIs), “function calls,” or “libraries,” we have each been involved since 
1988 or 1989 in creating, testing, and documenting the software that 
comprises the principal Software Development Kits (SDKs) for the 
NetWare operating system. The SDKs we have worked on range from 
the original NetWare API interface (NetWare Interface Tools or NIT) to 
the NetWare C Interfaces for DOS and Windows to various versions of 
the NWCalls interface for OS/2. We also worked together in 1993 to 
pull the sundry SDKs within Novell into the NetWare Client SDK for C. 





The NetWare Client SDK for C unified the NetWare API calls across 
DOS, OS/2, and Windows. For the first time, the APIs had the same 
names and the same parameters in all three operating systems. So 
while the subject of this book is using OS/2 to program with the 
NetWare Client SDK for C, the information presented is 
applicable to anyone programming in DOS or Windows.It will even 
apply to programs written for Windows NT and UnixWare if (and this is 
a very big if) Novell extends this API in the future. 


As a starting place, we’ve chosen to write this book for OS/2. However, 
in this book we do not attempt to reveal any secrets or expert tech- 
niques about programming in OS/2. This isn’t a book about threads or 
Presentation Manager (PM) or the intricacies of a 32-bit, multi-tasking 
operating system architecture. Rather it is a book about the NetWare 
requester for OS/2, Internetwork Packet Exchange (IPX), and the 
NetWare server architecture. In it we have tried to cover the entire 
range of services provided in the client SDK including the following 
areas: 


e NetWare Directory Services 


e Communication Services: IPX, SPX, SAP, Diagnostic 
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QMS services 
Bindery Services 
File System Services 
Connection Services 


Nevertheless, there are a few areas we have not covered. We do not 
cover any of the Print Server services because these calls are used to 
create a very specific kind of application, and we felt that discussion 
alone could occupy an entire book. Similarly we do not cover TLI, 
Named Pipes, NetBIOS, etc., because these topics also could fill books 
of their own. We have also not covered NetWare Core Protocol (NCP) 
extensions. Even though we recognize that NCP extensions are very 
useful APIs, using them involves some NetWare Loadable Module 
(NLM) programming, and, again, we felt it would take an entire book to 
do the topic justice. 





Theory and Application 


For us, nothing communicates information about NetWare APIs better 
than sample code. Indeed, we derive much of our “authority” from the 
fact that the sample code provided with this book compiles, links, and 
runs. Of course, no warranty or fitness for a particular use should be 
inferred from that last statement, but, after all the explication is over, 
you can, at your leisure, insert the sample code diskette in drive A and 
see how it works yourself. 


Still, there are concepts and strategies and algorithms that are useful to 
know ahead of time, before you dive into the code. Consequently, we 
have prefaced each “application” chapter with a “theory” chapter that 
explains the architecture of and vocabulary for that particular service. 


We realize, though, that some of you already know about NetWare 
client programming, so we have written the theory chapters so that you 
can skip over them—go right to the application chapter—without 
missing anything. If you find you still have questions with the 
application chapter, you can always refer back to the previous chapter. 
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We strongly recommend 
that you code the network 
portions of your applica- 
tions to be as user- 
interface-independent as 
possible. It may make your 
code a little bigger, but 
keeping the application 
portion and the network 
portion separate will make 
it easier to port the 
NetWare capabilities of 
your OS/2 programs to 
programs in Windows 

or DOS. 


Pedagogical Code 





The sample code we have provided on the diskette that accompanies 
this book is written to illustrate how NetWare APIs work. It is not 
production-level code. It is not optimized. Rather it is pedagogical 
code; it’s primary objective is to be readily decipherable. (Yes, peda- 
gogy is legal in Utah.) To accomplish this, we decided to do several 
things. 


First, we decided that we’d make many simplifying assumptions. These 
are assumptions like correct data is being passed into the application, 
values are falling within certain ranges, and that there are sufficient 
memory and disk resources available on the OS/2 client workstation 
and on the NetWare server. You didn’t buy this book to learn how to 
write a parser or do boundary checking. So we deliberately left out 
some of the things we would normally do 


For example, a key piece of the NetWare Client SDK is the NWLOCALE 
library which allows you to create applications that can accommodate 
other languages. (We’re talking Japanese here, not Pascal.) In practice, 
this involves removing all “clear text” from source files and retrieving 
text messages from an external file or database. So while we strongly 
recommend this practice to everyone, we felt that the layer of 
abstraction that language-enabled code introduced would conflict with 
our intent to make it easily understood. Besides, once you’ve learned 
how the APIs work, you can refer to our chapter on internationalizing 
your applications and, if you decide to, employ those strategies in your 
own programs. 


Also in the spirit of reducing visual noise, we decided not to write our 
sample code for PM. To us, Presentation Manager is all about making 
the user interface comfortable, while NetWare programming is about 
plumbing. Furthermore, we strongly recommend that you code the 
network portions of your applications to be as user-interface-indepen- 
dent as possible. It may make your code a little bigger, but keeping the 
application portion and the network portion separate will make it easier 
to port the NetWare capabilities of your OS/2 programs to programs in 
Windows or DOS. The fact that “stdio”-based programming is 
considerably easier, faster, more pleasant, and much less work than PM 
programming was never considered in this decision. 
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We have not printed all 
the sample code in the 
book. In the application 
chapters we do refer to 
fragments from the sample 
code, but if you want to see 
all the code in tts entirety, 
you will need to refer 

to the diskette. 


The final simplifying assumption that we made, is that we are not 
writing The Encyclopedia of NetWare. In a few places there are fields and 
variables that we have no idea why they’re there or what their 
significance is. In other places, there are variables and fields whose 
significance is irrelevant to the “usual” work people do with the APIs. 
So if there are fields or variables which are used only in rare or extreme 
cases or the information they provide is unimportant to the application 
at hand, we don’t comment on them. We realize that this will frustrate 
some of you who specifically want to know what some of these gnostic 
fields and assorted NetWare cabals are, and we apologize in advance. 


In our defense, we’d like to point out that in more than a few cases, 
nobody at Novell knows what certain fields and variables are either. 
This is not said to disparage the NetWare product, but rather to reflect 
the reality that the Netware operating system is so big, and so complex, 
and so many people have worked on it over the last eight or more years, 
that no one person or group knows it all. Of course, at the time, there 
were reasons for including these variables or fields in the server or the 
APIs, but finding the person who knows the information can be—even 
for people inside Novell—like bringing Cerebus to Eurystheus, the 
fabled twelfth labor of Hercules. 


As a final note on the sample code, in an effort to keep the size of this 
book manageable, we have not printed all the sample code in the book. 
In the application chapters we do refer to fragments from the sample 
code, but if you want to see all the code in its entirety, you will need to 
refer to the diskette. 


Enjoy the Book 





Overall, we are very pleased with this book. We think we’ve done a 
respectable job of covering the NetWare services available in the 
NetWare Client SDK, and in many places in this book, we have provided 
information that is either poorly documented in the Novell SDK refer- 
ences or not documented at all. To be sure, it is information that any 
determined programmer could eventually figure out on their own, but, 
if nothing else, we hope we can save you some time. What took hours of 
research on our part, will hopefully result in a few minutes of reference 
on yours. 
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This one was one who was working and he was one needing 
this thing needing to be working so as to be one having some 
way of being one having some way of working. 


—Gertrude Stein, “Picasso” 


Before you can really begin programming NetWare in OS/2, you will 
need to have completed the following preliminary activities: 


Have OS/2 installed and running 

Have a NetWare server running on your network 
Have the OS/2 requester installed and running 
Have a C compiler installed and running 


Have the NetWare Client SDK for C installed 





If you have two NetWare 


applications running 


simultaneously, one 
program could potentially 
block the execution of the 
other while 1t watts for a 
reply. This could also 
happen at the thread level 


uf your program has two or 


more threads that are 
making NCP-based 
NetWare calls. 


Multi-tasking and 
“Request-Reply” NCPs 


These are not trivial activities. At different times and with different 
configurations, any one of these activities could take 20 minutes or 20 
hours. One time OS/2 will install in 20 minutes; another time it will take 
4 hours. One time a NetWare server will come up perfectly in an hour; 
another time it will take three days to resolve interrupt conflicts, get the 
right drivers, get sub-systems running, and get IPX and network 
addresses assigned correctly. 


We will not attempt to summarize or re-write the currently available 
books on installing and using OS/2. Nor will we try to supplement the 
reams of documentation that came with our C compiler or Client SDK 
or NetWare Server. Rather, we will make a few comments and 
observations that we feel are important but may not be readily acces- 
sible in existing books or documentation. 


0S/2 Considerations — 





Probably the most attractive feature of programming in the OS/2 oper- 
ating system is its multi-tasking capabilities. The ability to execute 
simultaneous applications or simultaneous processes within the same 
application open up a multitude of opportunities to the programmer. 
The NetWare Client SDK fully supports this multi-tasking capability, 
and the dynamic link libraries (DLLs) provided with the OS/2 re- 
quester and the NetWare SDK are fully re-entrant. However, there is a 
potential limitation you should be aware of. 


NetWare Core Protocols (NCPs) are built on a “request-reply” model. 
That is, the client workstation sends a request packet to a server and 
then waits to get a reply packet from the server. This request and reply 
process happens very quickly, but it is sequential. Any request packets 
queued up by the NetWare requester must wait for the currently re- 
questing packet to receive its reply. 


This means that if you have two NetWare applications running 
simultaneously, one program could potentially block the execution of 
the other while it waits for areply. This could also happen at the thread 
level if your program has two or more threads that are making NCP- 
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NetWare Ring 0 Device 
Drivers 


Many of the “fatal” errors 
people experience in IPX/ 
SPX programming arise 
from passing bad pointers 
to the device drivers 
running at the kernel level. 


based NetWare calls. In most cases, though, you won’t notice a problem. 
The problem usually surfaces when a server goes down or a client 
workstation loses a connection, and the requester keeps resending the 
same request packet or it just waits for the request packet to time out. 


Unfortunately, this is currently an architectural limitation of NetWare. 
Removing it will require Novell to do some re-design on both the server 
and the client requesters. 


Another feature of OS/2 is its ring protection. This architecture keeps 
ill-behaved or “crashing” programs in one session from bringing down 
programs in another. This will also hold true for any NetWare pro- 
grams you write, unless the problem occurs in the device driver por- 
tions of the NetWare requester. 


All the files with a .SYS extension that the OS/2 requester install 
program puts in the CONFIG.SYS run at ring 0. Consequently, if these 
files get corrupted or if you exercise the requester in a way that exposes 
a “bug,” your entire workstation could hang. These situations should 
be very rare, but you should be aware that NetWare requester is 
running at the same level as the OS/2 kernel, and, consequently, could 
create or encounter potentially catastrophic errors. For example, many 
of the “fatal” errors people experience in IPX/SPX programming arise 
from passing bad pointers to the device drivers running at the kernel 
level. 


NetWare Server Considerations 





Getting a NetWare server running is no small task, though it is getting 
easier. The 2.2, 3.12, and 4.01 server install programs from Novell all 
made significant “ease-of-use” advances over their respective previous 
versions. In the old days, getting a 2.1x server running was a vite de 
passage not unlike the scene in the old television series Kung Fu where 
Grasshopper must move the red-hot cauldron of coals with his bare 
forearms. 
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0S/2 Name Space 
Support 





NetWare for 0S /2 


When you are installing the NetWare server, make sure you install the 
OS/2 utilities. These are usually placed under the PUBLIC subdirectory 
in a subdirectory named OS2. As a general rule, the first drive mapping 
you will make will be to the subdirectory that contains the OS/2 
utilities. 


You can also put the OS/2 utilities on your local drive. However, if you 
are copying the NetWare 4.x utilities local, be aware that, along with 
copying the utilities themselves, you must also copy the appropriate 
UNICODE files that are found in the PUBLIC/NLS subdirectory. 


If you want to have your NetWare drives support long OS/2 names, you 
will want to mount the OS/2 name space on each of the volumes you will 
be mapping to. This is done by entering the following two commands at 
the server console: 


load os2.nam 
add name space os2 to volume sys 


Depending on your server configuration, you may need to preface 
OS2.NAM with a local drive like “C:” so the NetWare server can find the 
file. 


Remember that adding the OS/2 name space to a volume (or any other 
name space for that matter) will cause each file on that volume to take 
up slightly more space, and that removing the OS/2 name space will 
require you to run the VREPAIR NLM against that volume. 


Again, this topic could be its own book. Installing the NetWare server 
on a machine that is currently running OS/2 adds yet another level of 
complexity to the server configuration process—especially if you are 
running the NetWare server and requester concurrently with the IBM 
LAN server and IBM LAN requester. However, once the NetWare 
server is configured and running, your interaction with it through the 
NetWare requester will be identical to your interaction with any other 
NetWare server. 
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NetWare 2.x Servers 


There is a significant 
installed base of NetWare 
2.x, and in most cases it 
would not be too difficult to 
make our sample programs 
work with 2.x servers. 


Thunking Headers 


There are more significant differences between the behavior of NCPs 
and APIs between 2.x and 3.x than between 3.x and 4.x. Consequently, 
we have chosen to largely ignore 2.x considerations. In fact, Novell has 
discontinued selling and manufacturing NetWare 2.x and is only honor- 
ing specific customer requests for the product until the current stock of 
2.X runs out. 


However, there is a significant installed base of NetWare 2.x, and in 
most cases it would not be too difficult to make our sample programs 
work with 2.x servers. It would be largely a matter of checking the 
server version and then passing the parameters that are required by the 
server version to which the function call is addressed. Still there are 
only a few APIs where the fields and variables have different meanings 
or values for 2.x servers as opposed to 3.x and 4.x servers. 


NetWare 0$/2 Requester Considerations 





Novell provides a substantial manual on installing the requester on your 
OS/2 workstation. However, we have provided a chapter entitled “The 
NetWare Requester for OS/2” that should give you a slightly broader 
context for how the requester functionality is provided. 


Compiler Considerations 





The most important thing to be aware of with your compiler is that the 
Application Program Interfaces (APIs) provided with the SDK are 16- 
bit. Novell created the .DLLs using the Microsoft 6.0a C compiler, and 
if you are using this compiler or a version that supports 16-bit code, you 
should have very few problems using the SDK. 


We think “Thunking Headers” would be a great name for a rock band. 
But that’s not why we wrote this paragraph. If you are using a 32-bit 
compiler like C SET/2 or Borland C++ for OS/2, you will either need to 
“thunk” the header files that come with the SDK or get the “thunked” 
header files from Novell. We had hoped to provide these thunked 
headers on the sample code diskette; however, we were unable to reach 
an agreement with Novell on distributing these files. 
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Appendix A in this book describes how to thunk the header files 
yourself. Unfortunately, this is an exercise you will have to go through 
before you can compile any of the sample code on the sample code 
diskette. You can also get the thunked headers from Novell off the 
NetWire forum on CompuServe. The file you will want to download is 
HCSDK5.ZIP, and you can call Novell’s developer relations at 1-800- 
NETWARE to get information about accessing the NetWire forum on 
CompuServe. If you get the thunked headers from Novell, be aware that 
develop the sample code there may be some additional modifications you will need to make to 

for this book. get the thunked headers to work. We've tried to cover most of these in 

Appendix A. 


We used the Borland 
32-bit C++ compiler to 


In case you're interested, we used the Borland 32-bit C++ compiler to 
develop the sample code for this book. This is mainly because the nice 
people at Borland sent us each a copy. 


Client SDK Considerations | 





If you will allow us a metaphor here, we'd like observe that the NetWare 
Client SDK has lots of “tree” documentation, but very little “forest” 
documentation. That is, the specific APIs themselves are fairly well 
documented, but their relationships to other APIs within the same 
service group go largely unexplained. And if we were to develop our 
metaphor still further into a conceit, you might say the biggest problem 
with the SDK is that you can’t see NetWare for the APIs. 


This book is largely our attempt to provide some of the “forest” docu- 
mentation, some of the relationships and sequences involved in using 
the APIs. Our chapter “The NetWare Client SDK for C” provides an 
overview of the SDK, and the subsequent chapters describe the theory 
and specific application of NetWare services. 


A Final Consideration 





Given that we have just glossed over a significant amount of work in a 
few pages, we thought we’d conclude with an important word of advice: 
don’t be ina hurry. But if you don’t have the luxury of time, keep this 
corollary advice in mind: expect complexity. 
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Lo, soul, seest thou not God’s purpose from the first? 
The earth to be spann’d, connected by network. 


—Walt Whitman, “Passage to India” 


Novell engineers use lots of jargon; they also use lots of acronyms. 
Consequently, Novell documentation, and even books written by Novell 
employees, can be difficult to read at times. This chapter, then, is our 
attempt to clarify some of the jargon we use throughout the book, to 
explain the vocabulary we will be using to talk about NetWare and 
networking, and to provide a general framework for the discussions of 
networking that follow. If you are already familiar with NetWare, feel 
free to skip ahead. 
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The distinction between 
LANs and WANS is often 
fuzzy, and about the only 
general rule of thumb for 

distinguishing between the 
two 1s distance 
between workstations. 


Routers 





In order to network at all, there must be some way for your workstation 
to communicate with other workstations. Workstations can communi- 
cate across Ethernet cables, telephone wires, satellite links, infrared 
transmitters, and ever growing list of other networking media. If the 
number of workstations you can communicate with is small or the 
physical distance between the workstations is small, the network can be 
considered a Local Area Network or LAN. If the number of worksta- 
tions you can communicate with is large or the distance between work- 
stations is large, the network can be considered a Wide Area Network 
or WAN. Also LANs are generally characterized by faster communica- 
tions than WANs. But the distinction between LANs and WANs is often 
fuzzy, and about the only general rule of thumb for distinguishing 
between the two is distance between workstations 


Linking Networks | 


Once people started linking workstations into LANs it was inevitable 
that they would eventually start linking LANs together to form WANs, 
and, consequently, specialized kinds of networking software were de- 
veloped to link networks together. 


For networks which use the same networking software—e.g., a network 
where all workstations and servers use NetWare networking software— 
and which use the same physical topology for all the networks seg- 
ments—e.g., all Ethernet or all Token-Ring LAN cards—the piece of 
software that allows the multiple networks segments to communicate 
with each other is called a router. Routers discover all the network 
segments that compose the WAN or inter-network, and they can ad- 
dress and send a packet either to the packet’s destination or to another 
router which is closer to the destination. For example, the Router A in 
Figure 3-1 can route packets to any node on 01010101 or it can route 
packets destined for nodes on ECB, FADE23000, or 02020202 to the 
router which exists on those network segments. 
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Be aware that some people 
use the term bridge and 
router interchangeably; 

however, you will do well 
use the term bridge only for 
software that “bridges” 
different networking 
topologies. 


Figure 3-1. Routers 
on an Internetwork. 


Bridges 


When we get to the point of using OSI terminology in a moment, we 
could say that routers connect networks that use the same “transport 
layer” but different “network layers.” A page or two from now we'll go 
into more detail about what this means. 


01010101 





If you have a network that uses the same networking software—e.g., 
NetWare—but the network segments use different networking topol- 
ogy, then the software that connects the network segments is called a 
bridge. For example, Figure 3-2 shows a bridge between an Ethernet 
network and a Token-Ring network. Be aware that some people use the 
term bridge and router interchangeably; however, you will do well use 
the term bridge only for software that “bridges” different networking 
topologies. 


Again, if we were to use OSI terminology, bridges are used to connect 
networks at the “Data-Link” layer. 
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Figure 3-2. Bridge A 
Connecting Ethernet 
Network BEEFOOOO 

with Token-Ring 
Network 12345678. 


Gateways 


BEEFOO000 [ 


Bric 


If you wanted to connect two networks wi... aca Cae werworking soft- 
ware—e.g., a NetWare network with an IBM mainframe network—you 
would need to have a piece of software called a gateway. For example, 
in order for a personal computer on a NetWare network to communi- 
cate with an IBM mainframe, you would need to “talk” across a gateway 
that translates NetWare-style communications into an SNA-style com- 
munications. 


Using OSI terminology, we could say that gateways usually link net- 
works at the application layer. 


Along with the necessity of a creating physical links between your 
workstation and the network, your workstation must also know the 
rules for communicating across those links. These rules are called 
protocols, and if your workstation doesn’t know the protocol it might as 
well not be connected to the network at all because none of the other 
workstations will talk to it. (They'll never let your workstation join in 
any workstation games.) 
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And there are lots of these protocols. There are protocols associated 
with sending packets on a physical media (e.g., protocols for sending 
packets on Token-Ring and Ethernet), there are protocols used to 
address packets to other workstations (e.g., IPX/SPX and TCP/IP), 
there are protocols that applications use to extract meaningful data out 
of the packets (e.g., knowing whether strings are length-preceded or 
NULL-terminated), and even protocols that workstations need to know 
in order to work correctly with other workstations on the network (e.g., 
how different workstations participate in file and record locking within 
a common database). 


This may seem a bit obvious, but with all the different kinds of rules and 
protocols your workstation needs to understand to communicate on the 
network, you need to understand that there are many possible points of 
failure. 


We'll give you an example of a fairly well-known break down in protocol 
communication. When Novell beta tested NetWare 4.0, a number of 
customers had problems upgrading their servers. They would take the 
old file server down, perform the upgrade, and then bring up the new 
file server on the network. But none of workstations could see the new 
server. Unfortunately, some sites went through agonizing re-installs 
and frantic calls to customer support before they figured out the prob- 
lem: Novell had changed the default frame type on the LAN drivers. 
NetWare 2.x and 3.x had, by default, used the 802.3 frame type to 
communicate across Ethernet cabling. On every packet that went out 
on the wire, the LAN driver (the software that talks directly to the 
network card) would add an 802.3 header which consisted of a six byte 
destination address, a six byte source address, and a two byte “packet 
length” field. However, beginning with NetWare 4.0, Novell changed 
the default frame type to 802.2. The 802.2 header is just like the 802.3 
header except it has three or four additional bytes of control informa- 
tion added on. Consequently, it wasn’t until after the workstations had 
been configured “to talk 802.2” or the server had been reconfigured to 
talk 802.3 that clients and servers could see each other again. 
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OSI Networking Model and NetWare 


In order to try and make some sense of how all these protocols fit 
together the International Standards Organization (ISO) put together a 
general model of how network protocols relate to each other. They 
called it the Open Systems Interconnection Reference Model—which 
nobody abbreviates as OSIRM, but rather is handily referred to as the 
OSI model. Now, very little networking software is engineered exactly 
along the OSI model, but the model does provide a useful framework 
for discussing network protocols. The OSI layers are illustrated in 
Figure 3-3, and the corresponding NetWare layers are illustrated in 
Figure 3-4. 





Data Link Transmission Techniques 
Figure 3-3. OSI Physical Physical Data Transmission 
Layers and Their 
Function. 


In the following paragraphs we'll talk about each of the layers of the OSI 
model and discuss how a NetWare network works at these layers. 
However, our intent here is to communicate a general idea about 
networking protocols, not give an exhaustive technical description of 
the OSI model. Please bear with us as we make several not-entirely- 
correct-in-every-instance statements. 
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Figure 3-4. OSI 
Layers and Corre- 
sponding NetWare 

Software. 


The Application Layer 


The Presentation Layer 


OSI Layer NetWare 


Application NetWare C 


NCP 


Network Protocol 
Stack 
(IPX) 

Data Link LAN Drivers 


(or MLIDs) 
Physical LAN Cards 





For our purposes, we just think of this layer as being where the applica- 
tion stuff happens. This is where the user interface is and where you do 
string manipulation and where you do error checking. Even if your 
program is not networked at all, it still does a lot of application layer 
activities. However, the primary network interface you’re concerned 
with on this level is the Client API for C. This is the interface that you 
pass all your data to. 


For example, if you were writing a simple messaging application called 
SEND that would allow workstations to send messages to other work- 
stations, you would pass your message, say “Call me Ishmael,” to one of 
the NetWare APIs. At this point your application really doesn’t need to 
know what happens to that data; it just needs to wait for the API to give 
itareturn code. However, just for fun we'll follow the data down the OSI 
stack. 


The Presentation layer of the model deals with how data is formatted or 
how it needs to be translated. For example, data encryption and 
decryption logically occurs at this layer. Additionally, the translation of 
any data from one code set definition (e.g., EBCDIC) to another (e.g., 
ASCII) logically belongs on this layer. 
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Figure 3-5. Header 
Attached to Data at 
the Application Layer. 


The Session Layer 


As a simpler example, we can again go back to our SEND utility. Inside 
the NetWare API that took our “Call me Ishmael” string, a “header” 
might be added to the string that tells how many bytes of data follow. In 
other words, the API may make our data a length-preceded string. This 
is illustrated in Figure 3-5. 


Header 


Data 





The Session layer essentially maintains connections between nodes on 
the network. Maintenance of these connections includes keeping track 
of connection addresses and sending periodic query or “watchdog 
packets” to the connections to that address to keep current on the 
status of the other node. 


In the case of our little SEND application, the NetWare APIs we might 
use will know they will be talking to a NetWare server and will, conse- 
quently, need to use a protocol NetWare servers understand. In 
NetWare this protocol is called the NetWare Core Protocol or NCP. To 
say it another way, the APIs know they will be engaged in an “NCP 
session” with the server so they will add an NCP header to the packet. 
A simplified illustration of thisis provided in Figure 3-6. (The three 
vertical dots between the rows of boxes is intended to represent el- 
lipses. That is, the illustration does not attempt to illustrate the exact 
field makeup of the NCP header.) 
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Figure 3-6. Header 
Attached to Data at 
the Session and 
Transport Layers 
(NCP Header not an 
Exact Representation 
of Fields). 


The Transport Layer 


NCP Header 





NetWare protocols combine the functionality of the Transport and the 
Session layers into one piece of software. On a NetWare network, five 
protocols are supported that provide this level of service: Sequenced 
Packet Exchange (SPX), NetWare Core Protocol (NCP), TCP, 
NetBIOS, and Named Pipes. SPX and NCP are NetWare-specific proto- 
cols. NCP is the transport/session protocol used to communicate 
between NetWare clients and servers. SPX is used to communicate 
between service agents and service providers in SMS (Storage Manage- 
ment System) and in the Print Server. TCP as a protocol was developed 
in the UNIX world and is supported by NetWare. IBM created two 
protocols, NetBIOS and Named Pipes. Both of these are especially 
important in OS/2 and are supported accordingly. 


The Transport layer is responsible for sequencing packets and guaran- 
teeing their delivery at the correct address. Sequencing involves send- 
ing and receiving packets in a certain order, and when packets arrive 
out of order the software at the transport layer can do a number of 
things: 


1) Throw away all the packets and ask for a retransmission 


2) Ask for a re-transmission of the packet it was expecting 


3) Hold all the packets, and when it thinks it has them all, sort the packet 


numbers to see if it really does. If it is missing packets it can them 
request the retransmission of the missing packets. 
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The Network Layer 


Guaranteeing delivery involves the ensuring that if the destination is 
alive and a route is available, the packets will arrive at the destination. If 
the destination is not alive or no route exists, the protocol will report the 
error condition. Typically, in order to assure guaranteed delivery, some 
form of “receipt” or “acknowledgment” is required. This acknowledg- 
ment can occur per packet, per set of packets, or per time period as 
defined by the Transport Layer protocol. 


If the world were a perfect place, we could refer back to our SEND 
application and provide an illustration of how an SPX header is added to 
the data we are sending across the wire. However, in reality, SPX and 
IPX headers get put on packets at the same time so we'll just skip down 
to the Network layer. 


Unlike the Transport layer where packets are sequenced and receipts 
and acknowledgements of delivery are often required, the Network 
layer is primarily responsible for addressing packets and, when neces- 
sary, routing these packets to the appropriate network. No guarantees 
of delivery are provided; the packet is addressed and sent off to it’s 
destination in the same way you would drop a letter off at the post office. 
That is, unless you specifically designate “return receipt requested,” 
you may never know if the letter arrives. In network terms this is called 
a connection-less protocol. 


In order to address packets and route them appropriately, NetWare has 
two protocols that use IPX: the Service Advertising Protocol or SAP and 
the Routing Information Protocol or RIP. Additionally, remember that 
SPX, NCP, NetBIOS, and Named Pipes are all built on top of IPX. That 
is, the programming interfaces defined by the various organizations 
that created the protocol are supported for the application to use, but 
underneath all communications occur on the network using IPX. Be- 
cause they all use IPX to communicate, these protocols can only com- 
municate with other workstations that have the ability to communicate 
using IPX. This requires the appropriate NetWare software to be 
loaded on each workstation. 
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Figure 3-7. Headers 
Attached to Data at 
the Transport and 
Network Layers (IPX/ 
SPX Header not an 
Exact Representation 
of fields.) 


The Data Link Layer 


Additional protocol interfaces supported by NetWare on the Network 
layer include NetBIOS datagram services and NetWare IP (Internet 
Protocol) support. NetBIOS datagram services allow applications to 
send buffers up-to-4 kilobytes in size. The NetWare NetBIOS software 
sends this data using IPX. NetWare IP support allows workstations on 
NetWare networks to use IP to communicate on the network with host 
machines. 


Referring again to our SEND example, additional headers are attached 
to our message at the Network layer. This is illustrated in Figure 3-7. 


IPX/SPX Headers 


NOP Header ¢ 


Data * 





The Data Link layer covers the transmission techniques used for com- 
munication on the network. In more specific terms, this is the work that 
the LAN driver does when it interacts with LAN card to send packets or 
“frames” out onto the network. In NetWare all LAN drivers are written 
to comply with the NetWare Open Data-Link Interface (ODI) specifica- 
tion for network drivers. And perhaps a little discussion of the ODI 
model is in order here. 
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By having both protocol 
stacks and LAN drivers 
register their entry points 
with the LSL, the ODI 
architecture allowed 
multiple protocols to use 
the same LAN driver. 


Figure 3-8. General 
ODI Model. 


In the old days, around 1989 or so, the NetWare LAN driver and IPX 
protocol stack were linked together—by a program called 
SHELLGEN.EXE—into a single program that was usually called 
IPX.COM. However, as Novell looked into supporting protocol stacks 
other than IPX, the design engineers decided to separate the LAN 
driver from the protocol stack. In addition to separating the two, they 
also introduced a “multiplexing” layer called the Link Support Layer or 
LSL. This resulted in the general ODI model described in Figure 3-8. 
By having both protocol stacks and LAN drivers register their entry 
points with the LSL, the ODI architecture allowed multiple protocols to 
use the same LAN driver. Conversely, it allowed one protocol stack to 
use multiple LAN drivers. This capability is illustrated by Figure 3-9. 


Protocol Stack 





Link Support Layer 


MLID 
LAN Driver 


The interface between the LAN driver and the LSLis called the Multiple 
Link Interface, and, consequently, the LAN drivers written to this 
interface are called Multiple Link Interface Drivers or MLIDs. The 
interface between the LSL and the protocol stacks is called the Multiple 
Protocol Interface or MPI, but, unfortunately, protocol stacks written to 
this interface are very rarely called MPIDs. 
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Figure 3-9. Examples 
of How Multiple 
Protocol Stacks Can 
Interact with Multiple 
LAN Drivers (and Vice 
Versa) in the ODI 
Model. 


One of the headers that the LAN driver puts on packets is the frame 
type header. As we mentioned earlier, the default for NetWare before 
4.x and 3.2 was 802.3 frame type headers. However, the current default 
for NetWare is 802.2. Figure 3-10 illustrates how an Ethernet 802.2 
header would be added to the data of our “Call me Ishmael” packet. 


802.2 Header 


( 


IPX/YSPX Headers < ; 





ii 
NI 
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Data NCF Header < 


Figure 3-10. Header 
Attached to Data at 
the Data Link Layer. 
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The Physical Layer 


Figure 3-11. Header 
Attached to Data at 
the Physical Layer 
(Media Header not an 
Exact Representation 
of Fields). 


The Physical layer is the layer that details the physical configuration of 
the network. Described at this layer is the physical media used to 
connect each segment of the network. This may consist of coaxial cable, 
twisted pair, fiber optics, infrared, cellular, or any other type of commu- 
nications media. Each of these media has different characteristics and 
constraints and will attach headers as their respective protocols re- 
quire. Figure 3-11 illustrates a media header being added to our “Call 
me Ishmael” packet. 





Media Header 


802.2 Header % 


Data 
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In NetWare the term 
“server” has a specialized 
meaning; it refers to a 
computer that is running a 
proprietary Novell 
operating system that has 
been optimized for 

sharing files. 


Clients, Servers and Distributed Processing 





Now that we’ve discussed some the networking software that connects 
workstations and even networks together, let’s return to talking just 
about a single network. In some networks, the role of the networking 
software may just be to communicate text messages between worksta- 
tions. In other networks, there may be some workstations that provide 
services—e.g., printing—to other workstations in the workgroup. Any 
workstation that accesses services or resources on another workstation 
is called a client, and any workstation that provides services or re- 
sources to another workstation is called a server. In NetWare the term 
“server” has a specialized meaning; it refers to a computer that is 
running a proprietary Novell operating system that has been optimized 
for sharing files. Hence, Novell servers are often called file servers. 
However, in a “peer-to-peer” network—that is, where all the worksta- 
tions are running the same operating system—some of these machines 
may be running additional software that allows them to function as 
servers. Strictly peer-to-peer networking happens only very rarely on 
networks and then only in limited ways like message passing between 
workstations. 


But back to clients and servers. Once you have machines functioning 
as clients and servers it makes “distributed processing” possible. This 
means that you can take the “work” your application does and have the 
client do some of the work and the server do some of the work. How you 
distribute the work is up to you. 


Note: Remember that the client and server pieces of a dis- 
tributed application can run on the same machine. 


For example, you could distribute the work of an application so that 
nearly all the work is done on the server and hardly any is done on the 
client. This essentially how the “terminal” paradigm on a mainframe 
works. That is, the server (or mainframe) does all the processing and 
the client (or terminal) just displays data coming in from the server. 
Another way to distribute processing is to have most of the work take 
place on the client and very little take place on the server. For example, 
you might have a game program where the client workstations do all 
the processing and display, but they use common semaphores that are 
located on the server to control the starting and stopping of different 
phases of the game. 
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In the best distributed processing, the applications or users should not 
need to know whether the work is being done on the client or the 
server. With NetWare for example, applications running on an OS/2 
workstation access files on the local “C:” drive in the exact same way 
that they access files on a network “P:” drive. Another example of 
“transparent” distributed processing on NetWare is printing. When a 
user directs an application to print to LPT1, he or she expects output on 
and deciding how a given printer. Neither the application nor the user needs to know if 
to distribute is where the LPT1is connected directly to the printer with a parallel cable or if LPT1 
art of network has been redirected to a NetWare queue that will be serviced by a print 
server or a remote printer elsewhere on the network. Either way the 
work is getting done, and, as is the case with most distributed process- 
ing, the work gets done faster. 


Deciding when to 
distribute an application 


programming lies. 


Deciding when to distribute an application and deciding how to 
distribute is where the art of network programming lies. In this book, 
the chapter entitled “A Queue Management Services Sample 
Application” provides a “make server” that allows the compilation of C 
programs and the linking of the object files into executables to all take 
place on remote machines. In effect, the chapter shows you how to 
build a “compile and link server” that any client workstation can submit 
jobs to. If such a “make server” system were put into use in a produc- 
tion environment, not only could programmers using older, slower 
machines (clients) compile on faster machines (servers), but it would 
also reduce the need for licensing a compiler for each machine the 
programmers are using. The compile server is the only machine that 
needs a licensed copy of the compiler. (Of course, this all depends on 
the license agreement governing the use of the compiler.) 


NetWare Services. 





The applications in this book are a small sampling of the applications 
that can be written to take advantage of the power of NetWare and 
distributed computing. Additional applications that can be 
implemented include accounting servers (that charge users for using 
network resources), authorization servers (that can automate the cor- 
porate signature getting process), mail servers, FAX servers, and many 
“service” resources that can be implemented on the network. 
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We have been working with NetWare and networks for several years 
now, and hardly a week goes by that somebody in a conversation 
doesn’t say “We should write a network application that does...” And 
while we generally object to marketing terminology, networks do in fact 
offer “boundless” computing as well as boundless opportunities for 
network software development. 
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I request you 
To give my poor host freedom. 


—William Shakespeare, Cortolanus 


The OS/2 operating system is ambitious. It not only provides its own 
unique operating system, but it also provides support for DOS and 
Microsoft Windows. Similarly, the NetWare for OS/2 requester is also 
ambitious. It not only provides IPX and NCP support to OS/2, DOS, and 
Win-OS/2, but it also provides support for Named Pipes, NetBIOS, and 
NDIS protocols. Consequently, when you look at the 70+ files that get 
copied during install, it can be difficult to sort out where all the files are 
supposed to go and where requester functionality is coming from. 
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In this chapter we will provide an overview of what functionality is 
available in the OS/2 requester kit and, where possible, identify which 
files are providing that functionality. To begin, we’ll group together all 
the files that are used to provide file and print support to the three 
operating systems within OS/2: 

e OS/2 

e DOS 

e Windows 
Then we'll look at the files that provide the following protocol support: 

e [PX 

e SPX 

e Named Pipes 

e NetBIOS 


And finally, we'll review the following functionality that is provided by 
assorted drivers and applications: 


e Dual Requester support with ODINSUP 
e Target Service Agent (TSA) for Storage Management Services (SMS) 
e NWTOOLS 


e NPRINTER 


User Utilities 
e Dynamic Load Libraries (DLLs) 


e UNICODE tables 
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Figure 4-1. General 
ODI Model. 








Core 0$/2 Requester Functionality 





Both the DOS requester and the OS/2 requester follow the general 
Open Data-Link Interface (ODI) model illustrated in Figure 4-1. From 
the bottom up, the four layers in Figure 4-1 perform the following 
functions: 


Requester or Shell 


Protocol Stack 





Link Support Layer 


MLID 
LAN Driver 








Network Interface Card 
or LAN Adapter 







e MLID—is the ODI compliant LAN driver. This layer is written to 


interact with a specific kind of network card or LAN adapter, and you 
select which MLID goes in your CONFIG.SYS file during the installa- 
tion process. The function of the MLID is to transmit and receive 
packets according to its media protocol, a function that involves adding 
(or stripping off) media specific headers like Ethernet 802.2 or Token 
Ring 802.2 headers. 
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e Link Support Layer—is the multiplexing layer between protocol stacks 
and LAN drivers. This layer makes it possible for multiple protocol 
stacks to drive a single LAN card, and, conversely, it allows multiple 

While the LSL is LAN cards to be driven by a single protocol stack. (While the LSL is 
represented as the second  Tepresented as the second layer, it is installed first because both LAN 


layer, it is installed first drivers and protocol stacks must register with the LSL.) 


because both LAN drivers Protocol Stack—is the protocol like IPX or IP that interprets protocol 

and protocol stacks must specific information, a process that involves adding (or striping off) 

register with the LSL. protocol specific headers from communication packets. In the case of 
IPX, this is the layer where IPX packets are built. 


e Requester—creates and maintains connections to the NetWare server 
and builds the NetWare Core Protocol (NCP) packets that are sent to 
the server. 


A Generic OS / 2 When you perform a “generic,” OS/2-only requester installation, a 

° number of entries are placed in the CONFIG.SYS file. These files and 
Requester Installation their relationships to the general ODI model are represented in Figure 
4-2. In addition, Figure 4-2 identifies the Ring level in OS/2 where the 
drivers and daemons run. “Daemons” in the OS/2 context should not to 
be confused with subordinate deities in Greek mythology. Rather, they 
are programs that provide an application context to the device driver— 
allowing it to allocate memory and display messages. Together, these 
drivers and daemons provide the basic NetWare functionality required 
by OS/2. Figure 4-3 restates the information in Figure 4-2 in a table 
format. 
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NWDAEMON.EXE 







DDAEMON.EXE 


eee) ee ee ee ee ee eee 


NWREQ.SYS 


IPX.SYS 


LSL.SYS 


NE2000.SYS 


Figure 4-2. OS/2 


Specific Instance of 
ODI Model. 










NWIFS.SYS OS/2 Kernel 
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SLS¥S 7 


DDAEMON.EXE a 
NE2000.SYS a 


IPY.SYS so 


NWREO.SYS a 
NWIFS.SYS - 


NWDAEMON.EXE 


Figure 4-3. 
Description of Files 
Used in Generic OS/2 
Requester Install. 


Description 


Link Support Layer. This is a multiplexor that 
mediates between protocol stacks and Multiple 
Link Interface Drivers (MLIDs) or LAN drivers. 
The LSL must load first because both protocol 
stacks and MLIDs register with the LSL when they 
initialize. 


LSL support daemon. Provides the application 
context for the LSL to allocate memory and dis- 
play errors and messages. 


Multiple Link Interface Driver (MLID). This driver 
will be selected during install. It will be the driver 
written specifically for your network card. 


IPX protocol stack. 


NetWare Requester. It builds NetWare Core 
Protocol (NCP) packets and maintains 
connections. 


NetWare installable file system. It transfers 
information between the 0S/2 kernel and the 
requester. 


Broadcast Message Handler. It also creates 
the initial drive mapping when the requester 
initializes. 
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0S /2 Requester 
Configuration 


You can use this editor to 
create your NET.CFG file. 
Be aware, however, that 
these are not all the 
possible section headings or 
key words that are 
available in the install 


program’s editor. 





The drivers that were installed in the CONFIG.SYS file can be config- 
ured by placing entries in the NET.CFG file. The NET.CFG file struc- 
ture consists of main section headings and subordinate key words and 


parameters. For example, to configure the LSL you might put entries 
like this in the NET.CFG file: 


LINK SUPPORT 
BUFFERS 8 1514 
MEMPOOL 5120 


The keyword BUFFERS would tell the LSL to create eight buffers with 
each buffer having the capacity of 1514 bytes for use in sending and 
receiving packets. The keyword MEMPOOL tells the LSL to allocate 
59120 bytes (or 5K) to be used as the LSL’s general services memory. 


The “Configuration” option in the NetWare requester install program 
provides an on-screen list of main section headings and subordinate key 
words. You can use this editor to create your NET.CFG file. Be aware, 
however, that these are not all the possible section headings or key 
words that are available in the install program’s editor. For example, the 
MEMPOOL option we used in the example above is not listed as a 
keyword for LINK SUPPORT. 


Figure 4-4 provides a partial list of device drivers and their associated 
main section headings in the NET.CFG. This list will always be partial 
because new section headings and key words are being added all the 
time. For example, when LAN WorkPlace for OS/2 was introduced, 
there were over 20 new key words added to the NET.CFG file to allow 
you to configure TCP/IP under the PROTOCOL TCPIP section 
heading. 


The requester uses the NWCONFIG.DLL to parse the NET.CFG file at 
initialization time. Your programs can also use this parser if you want to 
put your own program information in the NET.CFG file. The function 
call is NWParseConfig and is documented in the SDK reference. 
However, in spite of what the documentation indicates, this call is only 
available in OS/2. 
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Device Driver Main Section Heading in 





NET.CFG 
LSL.SYS Link Support 
NE2000.SYS Link Driver 
ODINSUP.SYS Protocol ODINSUP 
ROUTE.SYS Protocol Route 
IPX.SYS Protocol Stack IPX 
SPX.SYS Protocol Stack SPX 
NMPIPE.SYS and NPSERVER.SYS Named Pipes 
NWREQ.SYS NetWare Requester 
LANSUP.SYS Virtual MLID for LAN Sharing 
NETBIOS.SYS NetWare NetBIOS 
Figure 4-4. 
Device Drivers and 
Their Corresponding 
Main Section 
Headings in 
NET.CFG. 


Both DOS and OS/2 can keep configuration information in the same 
NET.CFG file. However, the big difference between “NetWare DOS 
Requester” syntax and “NetWare Requester” syntax (for OS/2), is that 
entries for OS/2 do not have an equal sign. For example, in DOS, you 
would specify a preferred server as follows: 





PREFERRED SERVER = PEQUOD 
But in OS/2, you would specify preferred server without the equal sign: 
PREFERRED SERVER PEQUOD 


Of course, this isn’t the only difference, but it is the one that causes the 
most confusion for users who switch between DOS and OS/2. 
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Some Network 
Considerations 


In the event that you have 
no NetWare Directory 
Services servers 

(NetWare 4.x) on your 
network, take the time to 
put DIRECTORY 
SERVICES OFF in your 
NET.CFG file under the 
“NetWare Requester” 
heading. 


Installing DOS Support 


The OS/2 requester is installed as device drivers in CONFIG.SYS, and 
these drivers load before you have an opportunity to provide user input. 
Generally, this doesn’t cause any problems, but it can if the requester 
can’t see a server on the network. In the case of a testing lab environ- 
ment, for example, you may or may not have servers up all the time. In 
the case where the server is down when the OS/2 requester tries to 
load, you will have to wait for the requester to time out and endure a few 
error messages before OS/2 finishes initializing. With a little foresight, 
though, you can avoid this minor irritation by writing a .CMD file that 
swaps a “NetWare CONFIG.SYS” with a “stand-alone CONFIG.SYS.” 


In the case where there is a server on the network but the OS/2 
requester can’t see it, you will want to check the frame type specifica- 
tion in the NET.CFG file before swearing too loudly at it. The OS/2 
requesters issues its initial “Get Nearest Server” call using the first 
frame type in finds in the NET.CFG. So if the server is only talking 
Ethernet_802.2 but the first “FRAME” entry in NET.CFG is 
Ethernet_802.3, the requester will never find the server. 


Also, in the event that you have no NetWare Directory Services servers 
(NetWare 4.x) on your network, take the time to put DIRECTORY 
SERVICES OFF in your NET.CFG file under the “NetWare Requester” 
heading. 


DOS and Windows Requester Functionality 





DOS and Windows functionality is provided in the requester by install- 
ing additional device drivers in CONFIG.SYS and some additional Ter- 
minate and Stay Resident (TSR) programs in AUTOEXEC.BAT 


When you elect to install DOS and Windows support in the NetWare 
requester install, VIPX.SYS, VSHELL.SYS, and LPTDD.SYS are added 
to the CONFIG.SYS. Additionally, NETX.COM and TBMI2.COM are 
added to AUTOEXEC.BAT. Figure 4-5 illustrates how the additional 
drivers and DOS programs are added to the generic OS/2 installation 
described in Figure 4-2. 
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NCP Requests 





IPX Requests 





IPX.SYS 


VIPX.SYS 


LSL.SYS 


NE2000.SYS 


Figure 4-5. NetWare 
Requester DOS 
Support. 


Along with OS/2 drivers, additional functionality is provided for Win- 
dows through some DLLs and Windows applications that ship with the 
requester. Figure 4-6 describes the files in the OS/2 requester that 
provide Windows and DOS support. 
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VIPX.SYS | 
VSHELL.SYS os 
LPTDD.SYS = | 


NETX.COM 
TBMI2.COM 


NWPOPUP.EXE 
NWNETAPI.DLL 


NETAPI.DLL 


NWIPXSPX.DLL 
N/A 


NETWARE.DRV 











Figure 4-6. 
Description of Files 
Used in DOS and 
Windows Support. 











Description 


Virtualized IPX and SPX driver. It allows DOS applications to 
access Protected Mode drivers. 


Virtual shell driver. Directs NETX.COM functionality from DOS to 
the requester. 


0S/2 print device driver. It provides network printing support to 
DOS. 


NetWare shell. This version is slightly different than the 
NETX.COM that shipped with the DOS and Windows client kit. 


Task-Switch Buffer Manager for IPX. This allows Windows 
applications that are SPX- or IPX-based to run in Windows’ 
standard mode in WINOS2. 


NetWare broadcast handler. This application displays broadcast 
messages in Windows. To use this application, you will need to 
put it in on the “load= line” of WIN.INI. 


NetWare (-Interface for Windows DLL. This DLL provides the NCP- 
based calls to Windows applications. This is the same DLL that 
ships in the Novell DOS and Windows client kit. 


Named Pipes DLL. This DLL supplies support for Named Pipes for 
Windows. It is the same DLL that ships with the Novell DOS and 
Windows client kit. Don’t confuse this Windows DLL with the 0S/2 
DLL of the same name that supplies NetBIOS support. 


IPX and SPX DLL. This DLL is the same DLL that ships with the 
Novell DOS and Windows client kit. 


Device driver for Windows that provides NetWare hooks for the 
Windows WNET calls. It also supplies a user interface that lets the 
user map drives and capture printers. 
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Global v.s. Private DOS 
Sessions 





NETX.EXE v.s. VLM.EXE 


The only way to use 
VLMs in the OS/2 
environment is to boot a 
“veal” version of 

“DOS from Drive A” 
using the 2.11 version 
of OS/2. 


With the OS/2 requester, DOS sessions can be either global or private. 
When you elect to have global sessions, VSHELL.SYS is loaded with the 
parameter GLOBAL which allows all DOS sessions to use the OS/2 
drive mappings and printer settings. For example, if you were using 
GLOBAL DOS sessions and your login script for OS/2 were to map 
drive Q: to server “TOWN-HO” and capture LPT1 to print queue 
LASERJET, every DOS session you started in OS/2 would have drive Q: 
mapped to TOWN-HO and the print queue LASERJET captured. 


However, if you were using private sessions, VSHELL.SYS would load 
with the parameter PRIVATE. Then, if you were to select a full screen 
DOS session, the session would come up with drive F: (the default 
mapping for NETX) mapped to SYS:LOGIN and, if you wanted to map a 
driver to TOWN-HO, you would have to log in. You could then map 
drives and capture printers. However, if you were to toggle back to the 
OS/2 desktop and select a DOS window session, this DOS session will 
know nothing about the drive mappings of either OS/2 or the DOS full 
screen session. It would come up with drive F: mapped to SYS:LOGIN. 


Private sessions can be a very useful feature for system administrators, 
as it allows them to login in to a server as both a regular user and as 
supervisor. And of course, you can have private DOS sessions logged in 
to completely different servers. 


In NetWare 4.x, Novell introduced redirector technology into its DOS 
client requester. In order to take advantage of NDS services, users 
needed to replace NETX.EXE shell with VLM.EXE requester. Unfortu- 
nately, however, the IBM version of DOS that boots in DOS sessions 
did not fully support the redirector hooks that were available in 
Microsoft DOS and Novell DOS. Consequently, the only way to use 
VLMs in the OS/2 environment is to boot a “real” version of “DOS from 
Drive A” using the 2.11 version of OS/2. Earlier versions of OS/2 
support running VLMs in a DOS session or Win-OS2 session; however, 
you will find sporadic bugs in some NetWare programs like 
NWADMIN. 
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NDS in DOS under 
0$/2 


Aside from the NDS functionality it provides, the biggest difference that 
users notice immediately, is that VLM.EXE requires your LASTDRIVE 
to be set higher than before. Where NETX required LASTDRIVE to be 
set to the drive letter of the last local device in your machine, VLMs 
require you to set LASTDRIVE to the highest drive letter you will want 
to use (usually Z). Depending on whether you are using NETX or VLM, 
you will want to set your DOS_LASTDRIVE setting accordingly. 


In order to run the DOS VLMs under OS/2, and consequently have 
access to NDS services in your DOS session, you use the “DOS from 
Drive A” feature provided on the OS/2 desktop. However, you will need 
to take the following steps in order for this to work correctly: 


1) Prepare a diskette that will boot “DOS from Drive A.” Be aware, 
though, that the some of the MS-DOS drivers and utilities are not 
compatible with OS/2. For example, you will have to run the OS/2 
version of HIMEM.SYS instead of the MSDOS version. And, as a 
general rule, you will want to use OS/2 versions of any DOS drivers or 
utilities whenever possible. 


2) Copy a “DOS from Drive A” icon from the “Command Prompts” folder 
onto the desktop. 


3) Make the following modifications to the DOS settings of the “DOS from 
Drive A” icon that is now on the desktop: 


e Set DOS_LAST_DRIVE equal to Z 
e Set NETWARE_RESOURCES to PRIVATE 


e Set DOS_AUTOEXEC to the AUTOEXEC.BAT file on your bootable 
diskette 


4) Add DEVICE=FSFILTER.SYS to the first line of the CONFIG.SYS file 
on your bootable diskette. You may have to preface FSFILTER.SYS 
with the correct path to the file (usually /OS2/MDOS). You will also 
want to be sure you are using OS/2 2.11 if you want NetWare programs 
like NWADMIN to run correctly. 


9) Add DEVICE=DOSVIPX.SYS to the CONFIG.SYS. Again, you may 
have to preface DOSVIPX.SYS with the path to the directory where you 
installed the requester (usually in a NETWARE subdirectory). 
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Configuration issues 
with “0S /2 for 
Windows” 





6) Finally, if you want to shorten the time it takes to boot “DOS from Drive 


A,” you can make a disk image of your bootable diskette and have 
OS/2 boot that disk image off your hard drive. 


To do this, use the VMDISK program in the OS2/MDOS subdirectory 
(which is an OS/2 program) to make the image of your boot diskette. 
Then, in the settings of your “DOS from Drive A” icon, you would set 
the DOS_STARTUP_DRIVE to the name of the file you created with 
VMDISK. Booting from your hard drive with an image of your boot 
diskette is significantly faster than booting from diskette. 


If you don’t use NDS functionality, the NETX support provided with the 
OS/2 requester should be sufficient. However, if you are currently a 
VLM user in DOS, then you may run into a potential problem with the 
product “OS/2 for Windows.” When IBM shipped this product, OS/2 
users were no longer required to use WIN-OS2. Instead, they could use 
the copy of Windows they had installed on their machine. This created 
a potential problem because before all the NETX compatible files were 
safely tucked away in OS2/ MDOS/WINOS2, and the VLM compatible 
were in another place like C\WINDOWS. But with OS/2 for Windows, 
both DOS and OS/2 use—and configure—the files in the MS Windows 
subdirectory. And the problem arises here because the 
NETWARE.DRV file used with NETX and the NETWARE.DRYV file 
used with VLMs are different. 


Consequently, when you install the OS/2 requester in OS/2 for 
Windows, the VLM specific NETWARE.DRV (version 3.0 and above) is 
renamed and the NETX specific version of NETWARE.DRV (version 
2.02 and below) is copied into the WINDOWS\SYSTEM subdirectory. 
So if you are in the habit of switching between using Windows in DOS 
and Windows in OS/2, you will need to come up with some “swap/ 
rename” scheme that will allow NETX or VLM to access the right 
NETWARE.DRV. 
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Sequenced Packet 
Exchange (SPX) 


Named Pipes 


NetBIOS 


Protocol Support 





Along with the core NCP and IPX support, the NetWare OS/2 requester 
also supports a number of other protocols. If you look at the 
CONFIG.SYS after the requester has been installed, you will see that 
most of these additional protocol device drivers have already been put 
in the CONFIG.SYS file, but they have been remarked out—i.e., the 
device driver is prefaced with the REM statement. You can run the 
install program to reconfigure these protocols—that is, to remove the 
REM statements—or you can do it manually by editing the 
CONFIG.SYS. The trick to doing it manually is knowing what to 
“unremark,” and the following paragraphs may help. 


SPX support is provided by the SPX.SYS device driver and the 
SPDAEMON.EXE daemon. 


Named Pipes support is provided by the NMPIPE.SYS device driver 
and the NPDAEMON.EXE daemon. Additionally, if you want to config- 
ure your OS/2 workstation to be a Named Pipes server, the install 
program will install the NPSERVER.SYS device driver. The name for 
your Named Pipes server is provided as a parameter to the 
NPDAEMON. For example, the line 


RUN=C: \NETWARE\NPDAEMON.EXE JUNGFRAU 
would cause your workstation to broadcast as the Named Pipes server 


JUNGFRAU (providing of course that NPSERVER.SYS was loaded 
first). 


NetBIOS support is provided by the NETBIOS.SYS device driver and 
the NBDAEMON.EXE daemon. 
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Dual Requesters 


Figure 4-7. Dual 
Requester Configura- 
tion Using Two 
Network Cards. 


Support for Dual Requesters and Servers 





Running both the NetWare requester and the IBM LAN requester is 
really a quite straightforward configuration if you have two network 
cards in your machine—a card for each requester. Running NetWare 
for OS/2 and the NetWare requester is also quite straightforward if you 
have two cards—one for the server and one for requester. Running a 
NetWare server, an IBM LAN server, the NetWare requester, and the 
IBM LAN requester on the same machine is also straightforward if you 
have three or four different LAN cards in your machine. But if you only 
have one card in the machine, the servers and requesters would have to 
share the same card. And more confusion arises from this “sharing” 
than any other aspect of the NetWare requester. 


As we said, the simplest “dual requester” configuration is to have two 
network cards in the machine. In this way, the NetWare requester can 
use its ODI stack to “talk” to a network card, and the IBM LAN 
requester can use its Network Driver Interface Specification (NDIS) 
stack to talk to the other card. Figure 4-7 illustrates this configuration. 
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Driver 
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When you elect to install 
ODINSUP, the NetWare 
ODI driver becomes the 
primary driver in the 


machine. 


Figure 4-8. 

Dual Reqester 
Configuration Sharing 
One Network Card. 





Another “dual requester” configuration would be to have the NetWare 
requester and the IBM LAN requester share the same card. This 
creates a small difficulty, of course, because NDIS and ODI are very 
different communication stacks. Novell’s solution to this card sharing 
problem was ODINSUP which provided a communication link or “shim” 
between the NDIS drivers and the ODI drivers. 


When you elect to install ODINSUP, the NetWare ODI driver becomes 
the primary driver in the machine. The install program goes into your 
LAN requester configuration and replaces your NDIS driver with the 
ODINSUFP driver. To the LAN requester, ODINSUP looks and behaves 
just like an NDIS driver. However, when the LAN requester isn’t 
looking, ODINSUP transfers all NDIS packets from the LAN requester 
to the ODI driver. And because ODI drivers are significantly faster than 
NDIS drivers, this “shim” results in a very small performance hit 
(around 5%) for the LAN requester. Figure 4-8 illustrates this 
configuration. 
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Note: ODINSUP will allow the IBM LAN requester to talk to 
any network card for which there is an OS/2 ODI driver. 
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Server Support 


Figure 4-9. 

Dual Requester 
Configuration with 
LAN Server Sharing 
One Network Card. 


Along with having requesters share the same card you can also have a 
server share the same card with the requester. For example, Figure 
4-9 shows how IBM LAN server could also use ODINSUP to share the 
same card with the IBM LAN requester and the NetWare requester. 
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Figure 4-10. NetWare 
Requester Sharing a 
Network Card with the 
NetWare Server. 


Things get more complicated, though, if you put the NetWare server on 
the same machine. If you are using NetWare for OS/2 (which is a 
separate product from the NetWare requester) the NetWare server 
driver becomes the primary driver in the machine. This server driver is 
a NetWare Loadable Module (NLM). The NetWare requester’s driver 
becomes secondary in this configuration and is replaced with a driver 
(supplied with NetWare for OS/2) called LANSHARE which transfers 
all requester packets to the server driver. Figure 4-10 shows how 
NetWare for OS/2 shares the same LAN card with the NetWare re- 
quester. In this configuration, the requester does not have to “hit the 
wire” to talk to local server whereas in a two card solution it would. 
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Figure 4-11. Dual 
Requesters Sharing 
the Same Card with a 
NetWare and IBM 
LAN Server. 


Figure 4-11 shows how the IBM LAN server and the IBM LAN re- 
quester would share the same card with the NetWare server and the 
NetWare requester. 
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TSA for SMS 


NPRINTER 


NWTOOLS 


NetWare User Utilities 


Note: At the time this book went to press, NetWare for 
OS/2 only supported card sharing between the requester 
and the server on IBM Token-Ring cards. This is why you 
see a Token-Ring bridge added to Figures 4-10 and 4-11. 


Additional Functionality 





There are a number of additional applications and utilities that also 
make up the NetWare requester. 


TSA stands for Target Service Agent. It is used by Storage Management 
Services (SMS) to back up your local drives. Use TSA_OS2.EXE to 
configure and run the target service agent on your local workstation. 


If you have a printer attached to your workstation, you can use 
NPRINTER.EXE to allow other users on the network to print to your 
printer. We won’t explain the NetWare printing paradigm here, but you 
will have to configure your network’s print server to send jobs to the 
NPRINTER running on your machine. 


NWTOOLS is a Presentation Manager utility that most people use to 
attach to servers and map drives. (It differs from the LOGIN utility in 
that it does not execute login scripts.) However, NWTOOLS also allows 
you to display a variety of status relating to the connections the NetWare 
requester has made. That is, you can display attached servers, mapped 
drives, directory trees, the user list on the default server, captured 
printer ports, and print queue activity. All of these features are dis- 
cussed in the NetWare requester for OS/2 documentation. 


The NetWare requester for OS/2 also ships with a number of user 
utilities. These utilities are described in Figure 4-12, but be aware that 
since we went to press with this book, some utilities may have been 
removed and others may have been added. 


The NetWare Requester for OS/2 51 





Figure 4-12. 
Additional User 
Utilities Supplied with 
the NetWare 
Requester. 


NetWare Dynamic Load 
Libraries (DLLs) 















CX.EXE Allows you to view and set your current NDS context. 


LOGIN.EXE Allows you to log in to a file server on an NDS tree. This utility 
executes login scripts. 

MAP.EXE Allows you to map drives to specific subdirectories on the NetWare 
server. (All drive mappings in 0S/2 are mapped “root.”) 


NLIST.EXE 






Allows you to view information about users, groups, and other objects. 
(The command NLIST SERVER /B is particularly useful as it displays the 
available servers on the network.) 


A number of DLLs get copied to the NETWARE subdirectory during 
the installation process. Some of these are “utility” DLLs, like 
INSTALL.DLL which is used to support the INSTALL program. Some 
of these are “requester level” DLLs, like NWWORKER.DLL which 
continually scans the netware requester drivers for messages and then 
displays them. And some of them are “library” DLLs. The library DLLs 
that contain APIs your programs can call are all described in the next 
chapter “The NetWare Client SDK for C.” 


You will want to make sure that the subdirectory that contains these 
DLLs is in your LIBPATH, and you will also want to make sure that you 
have the latest library DLLs in the NETWARE subdirectory. You will 
have to decide whether these DLLs will be the DLLs that shipped with 
the latest NetWare requester or the DLLs that shipped with latest SDK. 
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UNICODE Tables 


The OS/2 UNICODE 
files are identical to 
the UNICODE files 
used in DOS. 


Figure 4-13. 
UNICODE Files 
Needed to Use Code 
page 437 in the 
United States. 


To facilitate expanding its multi-language support for NetWare, Novell 
designed NetWare Directory Services to communicate across the net- 
work using UNICODE. This is why the first thing you have to do when 
you program to NDS is call NWInitUnicodeTables. UNICODE is double- 
byte character set that is capable of handling characters in every 
language—English, Japanese, Korean, Arabic, Hebrew, etc. 
(Technically though not every language is implemented yet.) In order 
to support multiple languages, Novell supplies the files necessary to 
translate the characters your workstation’s operating system is using to 
UNICODE and vice versa. Novell also supplies files to “monocase” 
characters (which is roughly analogous to uppercasing characters) and 
to collate characters (roughly analogous to alphabetizing). There area 
set of four files that get initialized by NWInitUnicodeTables, and the set 
most commonly used in the United States are listed in Figure 4-13. A 
fuller description of UNICODE and other language related 
programming issues is presented in the “Internationalization” and the 
“Internationalizing your Applications” chapters. 


UNICODE File Description 


437 _UNI.001 Contains the tables necessary to convert characters in code page 
437 to UNICODE in the United States. 


UNI_ 437.001 Converts UNICODE characters to characters in code page 437 in 
the United States. 


UNI_COL.001 Contains the collation tables for UNICODE characters in the United 
States. 


UNI_MON.001 Contains the monocasing tables for UNICODE characters in the 
United States. 





The UNICODE files are installed in the NETWARE subdirectory on 
your local hard disk, and they are also available on the file server under 
the PUBLIC\NLS subdirectory. And, in case you’re wondering, the 
OS/2 UNICODE files are identical to the UNICODE files used in DOS. 
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“Everything’s all right, now, except tools; and that’s easy fixed.” 


“Tools?” I says. “Tools for what?” 


—Mark Twain, Adventures of Huckleberry Finn 


The NetWare Client SDK for C | 


In 1992, Novell made the decision to give software developers access to 
the same development tools its engineers used internally to develop 
network applications. Consequently, Novell suspended new develop- 
ment on the software development kits (SDKs) that were then available 
through its developer support programs and focused it’s application 
program interface (API) resources on turning several internal software 
libraries into fully documented developer products. The result in 1993 
was the shipment of the 1.0 version of the NetWare Client SDK. 


OO 





For OS/2 developers the new SDK looked very familiar. After all, it 
contained the latest version of the NWCALLS library that had been the 
programming interface for the OS/2 NetWare requester since 1989. 
Some new libraries and APIs had, of course, been added, but for the 
most part the NWCALLS.DLL was fully backward compatible with the 
previous version. The bulk of the Novell engineering effort with the 
new SDK had been to provide the identical API functionality in an 
NWCALLS.DLL for MS Windows and an NWCALLS.LIB for DOS. 


For the first time, then, developers had the same API interface in DOS 
as they did in Windows as they did in OS/2. In theory, this meant that 
if a developer wrote the NetWare specific portions of his code in OS/2, 
that same code would compile and link in DOS and MS Windows with 
no changes whatsoever. In practice, though, there are always a few 
minor accommodations that need to be made for each operating sys- 
tem, but the logic and flow of the code is always the same. The 
necessary changes are so minor in fact, that, with relatively few condi- 
tional compile flags, Novell engineers were able to “single source” the 
code for the libraries across DOS, OS/2, and Windows (and in the case 
of the NWNET.DLL extend the interface into a NetWare Loadable 
Module library, DSAPI.LNLM). Many of the NetWare utilities took 
advantage of this also, and used a single source file for both DOS and 
OS/2. 


So while this book deals specifically with interfacing with the NetWare 

DLLs for OS/2, nearly all the information provided is applicable to 

NetWare developers who want to write for DOS and Windows. All the 

NetWare server information provided in this book holds true regard- 

the SDK is that it is 16-bit egg of client operating system, and all the sample programs in this book 
API. Ifyou are usinga_ will port very easily to DOS and (with somewhat more effort) to 
32-bit compiler you will Windows. 

need to “thunk” the header 


files before compiling the 


The only real drawback to 


The good news for OS/2 developers is that even though the SDK also 
supports DOS and Windows, the SDK is at heart an OS/2 SDK. Itis not 
sample code. 41)QS SDK with DOS biases nor a Windows SDK with Windows biases. 
All the APIs are fully re-entrant, the OS/2 name space is supported, and 
all the APIs run in protected mode. In fact the only real drawback to the 
SDK is that it is 16-bit API. If you are using a 32-bit compiler you will 
need to “thunk” the header files before compiling the sample code. The 
specific changes you will want to make to the header files are detailed in 
Appendix A. 
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Installing the SDK 


Figure 5-1. Directory 
Structure and Disk 
Space Requirements 
for the NetWare Client 
SDK. 


If you are using the first version of the SDK that came on diskette, there 
is no install program. A README.TXT file on diskette number 1 
(labeled “NWC1001”) recommends performing an XCOPY /S com- 
mand on each diskette. Ifthe target directory of the XCOPY commands 
is a subdirectory named DEV, the SDK will be installed in the directory 
structure illustrated in Figure 5-1. You can, of course, copy the SDK 
files into any directory structure you wish, but this may require you to 
rebuild the make files provided with some of the sample code. 


DEV DOS MSC 
BC 
OS2 
WIN 
INCLUDE DOSNP 
WINNP 
SAMPLES WHO 
DIRSVC 
SOK Tor DOS, OS/2, CONNECT 
and Windows BINDERY 
184 Files {LI 
6 Mbs disk space BRAINSHR 
Diskettes 1-/7 
DEY OS2 
ones 
WINNP 
SAMPLES WHO 
DIRSVC 
SDR Tor OS/2 CONNECT 
143 Files BINDERY 
2.3 MDS TLI 
Diskettes 5 and 7 BRAINSHR 


(and copy README.TXT from 1) 
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If you install the entire SDK, it will take up approximately six megabytes 
of disk space. If you install only the OS/2 libraries and the sample 
programs, it will take up approximately two and a half megabytes. (The 
sample programs take up about half a megabyte.) 


If you are using the SDK distributed on CD—labeled the “Promotional 
CD” with dates of 2/22/94— there is an installation program that will 
essentially do the XCOPY for you. However, since the CD doesn’t come 
with printed manuals, the installation program also helps you set up 
your on-line documentation viewer. Both SDKs install essentially the 
same way; the only difference being that the BrainShare sample code 
that came with the diskette version is not on the CD version. If you have 
the CD version and want the BrainShare sample code it is available on 
CompuServe in the NetWire forum. 


Include Files Most of the include files (or .H files) provided by the SDK define the 
structures, function prototypes, and constants necessary to access 
NetWare services. These services are organized into 31 groups, and 
Figure 5-2 lists how the include files correspond to these service groups. 
However, there are a few include files that serve a different purpose. 


Figure 5-2. 

NetWare Services and 
Corresponding 
Header Files. 
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Figure 5-2. 

NetWare Services and 
Corresponding 
Header Files. 
(Continued) 





Directory (Directory Services) nwnet.h 
nwdsacl.h 
nwdsapi.h 
nwdsasa.h 
nwdsattr.h 
nwdsaud.h 
nwdsbuft.h 
nwdsdc.h 
nwdsdefs.h 
nwdsdsa.h 
nwdserr.h 
nwdsfilt.h 
nwdsmisc.h 
nwdsname 
nwdsnmtp.h 
nwdspart.h 
nwdssch.h 


nwdstype.h 
File Server Environment nwise.h 
nwserver.h 


File System nwdentry.h 
nwdirect.h 
nwtile.h 

Internationalization unicode.h 
nwlocale.h 


IPX ipxcalls.h 
ipxerror.h 
nwipxmrg.h 
nwipxspx.h 
nxtd.h 


a 
a 
nwnamspc.h 


Name Space 
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Figure 5-2. 

NetWare Services and 
Corresponding 
Header Files. 
(Continued) 






NetWare Service Header Files 










NetBIOS ncb.h 
netbios.h 
netcons.h 















Print Server nwpsrv.h 
nwps_cfg.h 
nwps_com.h 
nwps_def.h 
nwps_err.h 
nwps_job.h 
nwps_pdf.h 
nwps_pkt.h 


nwprint.h 
nwredir.h 









spxcalls.h 
spxerror.h 
nwipxspx.h 


nxtd.h 


Volume nwvol.h 
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NWALIAS.H 


If you compare the documentation for a function call in the API refer- 
ence with its declaration in the include file, it may seem as though the 
data types of parameters don’t match. For example, the documentation 
for NWGetObjectID describes the parameter objectType as being type 
NWOBJ_TYPE whereas the include file NWBINDRY.H declares the 
parameter to be type WORD. The two types compile into the same size 
parameter, and NWALIAS.H is the include file where the types used in 
the documentation are defined to be the types used in the include files. 


This additional level of abstraction was put into the documentation to 
anticipate the next logical progression in Novell developer tools-a full 
32-bit API. By using the types defined in NWALIAS.H, you will not be 
tied necessarily to a specific parameter size, making it easier to change 
the size as necessary. The advantages to this level of abstraction can be 
demonstrated in the following scenario. 


Suppose you write some network applications using the NetWare Client 
SDK. Then suppose that Novell-and we are not saying Novell will- 
shipped a 32-bit SDK where most of the parameters were 32 bits long to 
optimize parameter passing on the stack. To port your applications to 
the new SDK you would simply re-compile with the header files in- 
cluded in the new SDK, and the definitions in NWALIAS.H would 
default to the settings detected on the system. While this “.H switch” 
won't solve all the porting problems of this scenario, it does alleviate the 
bulk of the porting work. 


Note: The Print Server Services APIs are not documented 
using the abstracted data types defined in NWALIAS.H 


If you are the type of programmer that doesn’t like to use “abstracted 
types,” you are perfectly free to declare parameters in the way you 
prefer. You can ensure that the parameters are the same size using the 
information in NWALIAS.H which is also printed as Appendix B in the 
NetWare Programmer’s Guide for C. 


In this book, however, we will refer to parameter types as they appear in 
the documentation. 
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NWBINDRY.H 


In the NWBINDRY.H header file there is a possible point of confusion 
that arises from byte-swapping on Intel processors. Intel represents 
WORD values in a low-high or “little-endian” format. That is, byte 0 is 
the low order byte. However, NetWare puts some WORD values “on the 
wire” in high-low or “big-endian” format. That is, byte 0 is the high 
If you were to call order byte. 
IpxOpenSocket and set the 
parameter usSocket to the NetWare libraries handle the byte swapping for you; however, 
Deb 204 you would be when writing your application you may need to declare bindery object 
: Ids, and socket numbers, and other NetWare-kinda-stuff in a “non- 
opening the SAP socket, . , «,. 5 . 
Pet, intuitive” way. For example, if you were to call I[pxOpenSocket and set 
which is generally referred the parameter usSocket to 0x5204 you would be opening the SAP socket, 
to in Novell documentation which is generally referred to in Novell documentation and polite 
and polite conversation as conversation as socket 452. The problem is Novell documentation (and 
socket 452, ©ven polite conversation) is not consistent in which order they present 
socket numbers and bindery object IDs. 


To be on the safe side, we'll provide another example. Let’s say you 
were using the call NWScanObject to find the names of all the file 
servers on your network. You would set the parameter searchType to 
0x0400. This is does not mean object type 400. Rather, it is a swapped 
value for 0x0004, which is the bindery object type for file server. 


Since this book focuses on writing applications for NetWare, object 
types in our examples, code fragments, and tables will reflect how you 
will see things specified in the SDK header files. 


NWCALDEF.H 


The NetWare SDK, you will remember, provides you with the same 
tools that Novell engineers use to write networking applications which 
is a tremendous benefit to non-Novell developers. However, it does 
occasionally have its drawbacks. 


The OS/2 DLLs in the SDK and all of the Novell utilities for OS/2 were 
developed using the Microsoft 6.0 compiler. Consequently, the header 
files are heavily oriented toward the Microsoft compiler. In order to use 
a different compiler you may need to make changes to NWCALDEF.H. 
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NWERROR.H 


In the NetWare SDK, the return code for the successful execution of a 
function is usually 0. There are some APIs that don’t follow this rule 
(like SPXInitialize for DOS and Windows which returns OxFF on suc- 
cess) but they are few and far between. However, as a general rule, if 
any other value—positive or negative—is returned it indicates the func- 
tion could not execute successfully. These values and their associated 
constant names are documented in Appendix A of the NetWare Client 
API for C Volume II. The same information can also be found in the files 
NWERROR.H, NWDSERR.H, NETERR.H, and NWPS_ERR.H. 


In previous Novell SDKs, most of the errors returned from the server 
were OxFF, ERR_OF_SOME_SORT. This was not the fault of the SDKs 
as much as it was the NetWare servers that were returning these codes 
to the client workstations. However, in the 1.0 version of the NetWare 
Client SDK a good deal of effort was put into making the return codes 
more meaningful. Though the schemes put into place are far from 
universal, it is an important start. 


NWDSCCODE 


NWNET.DLL contains all the network specific or directory services 
calls, and all its functions return 32-bit values. The upper 16 bits of 
these values are all set to -1, or OxFFFF, to sign extend the value of an 
error. The lower 16 bits, though, should be treated as a signed value 
and are significant in the ways described in Figure 5-3. 
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Lower 16-bits Significance 
(decimal value) 
-] to -255 These are not Directory Services specific errors, rather they are 
errors that Directory Services encountered while trying to execute 
on the NetWare server. 


-301 to -399 These errors are generated by NWNET.DLL or NWNET.LIB. The 
error was detected by the function call executing inside the client 
libraries. 


-601 to -699 These errors are returned from the Directory Services NLM 
running on the server. They specifically refer to errors generated 
by Directory Services. 


Figure 5-3. 
Significance of Lower 
16-bit Decimal Values 
in NWDSCCODE. 





NWCCODE 


NWCALLS.DLL contains the server specific calls, and the majority ofits 
functions return 16-bit values. When the upper 8-bits if this value are 
0x89, it signifies that the lower 8-bits of this code are a value returned by 
the server. If the upper 8-bits contain the value 0x88 this signifies that 
the lower 8-bits of this code are a value returned by the NetWare 
requester or shell. And at times, but not always, an upper 8-bit value of 
0x87 can indicate an error originating with the local operating system. 


There are, however, exceptions to these error code rules, and 
NWCALLS.DLL can’t always determine where an error comes from. 
Occasionally you might see a server error prefixed with 0x88. Further- 
more, errors generated by the OS/2 operating system may not follow 
any pattern at all. And, if you’re trying to write portable code, be aware 
the same error condition in DOS and OS/2 may yield different error 
codes through NWCALLS library. 
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Libraries 


The function NWCallsInit 
must be called before 
calling any of the other 
functions in the 
NWCALLS library. 


Other Return Values 


The return values associated with Print Server Services and the interna- 
tionalization functions were assigned arbitrarily, and beyond the docu- 
mented meaning of the value, there is no system or significance associ- 
ated with them. 


Included Includes 


NWCALLS.H is an include file which includes all of the include files 
available in the SDK. By defining certain constants, though, you can 
signal the compiler to not compile unnecessary headers. For example, 
defining NONTTS_INC at the beginning of your code will keep the 
NWTTS.H include file from compiling. 


The functionality of the Client SDK is spread across 10 libraries. These 
libraries and a brief description of their functionality are listed in Figure 
5-4. The detailed functionality of these libraries is described in the 
subsequent chapters of this book; however, there are a few important 
items they you should note about the following libraries: 


NWCALLS 


The function NWCallsInit must be called before calling any of the other 
functions in the NWCALLS library. This function initializes the interna- 
tionalization capabilities of the library, and, in DOS and Windows, 
detects the entry points for NETX.COM or VLM.EXE. For OS/2 
programmers this is not an issue because NWCallsInit is called when 
NWCALLS.DLLis loaded. If you are planning to port your code to DOS 
or Windows you will want to include this call in your code as calling 
NWCallsInit multiple times will cause no problems. 


You will also want to be aware of the “case” of strings you pass to 
functions in the NWCALLS library. Paths relating to DOS name spaces 
must be upper-cased and server names should be uppercase also. The 
NWCALLS library does not uppercase any strings. 


NWNET 


The Directory Services functions contained in this library use 
UNICODE in all the packets they put on the network. This does not 
mean there is a UNICODE name space on the server; only that Direc- 
tory Services does all its communication in UNICODE. Consequently, 
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before using any Directory Services calls, your program must call 
NWInitUnicodeTables successfully. (NWNET.DLL also has a depen- 
dency on NWCALLS.DLL so you will need to ensure that it is in your 
LIBPATH.) 


Before using any You will also want to increase the amount of stack space you allocate in 
any program using Directory Services. In fact, for first time program- 
mers of directory services, “increase your stack space” is very often the 
solution to their initial problems. After determining the stack space 
your program will need, add an additional 6 KB to the size of the stack. 


IPXCALLS and SPXCALLS 


Beginning with version 2.10 of the NetWare Requester for OS/2, IPX 
and SPX are supported in Enhanced Mode under Win-OS/2. 


Library Functionality 
Availability 
IPX calls 
NetBIOS calls 
Named Pipe calls 


Server specific NetWare calls 
(they make calls to a specific 
server) 


Directory Services calls, 
your program must call 
NWIn1tUnicodeTables 
successfully. 


NetWare NET.CFG parsing 
function 


Locale and UNICODE calls 


Network specific NetWare calls 
(they make calls to Directory 
Services) 


Print Server Services Calls 





Figure 5-4. 
Functionality of the 
Client SDK Libraries. 
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Figure 5-4. 


Functionality of the 


Client SDK Libraries. 
(Continued) 


Documentation 


Library Previous Functionality 
Availability 


SPXCALLS.LIB 05/2 Developer's Kit SPX calls 


TLI-LIB TLI SDK TLI calls 





There are five manuals that accompany the Client SDK, which comprise 
over 2,000 pages of documentation. Generally, the documentation is 
very good, and Novell has gone to great pains to ensure its accuracy. 
However, the documentation does have the failing of being a reference 
for Novell engineers who share a large body of knowledge of how 
NetWare APIs work together. 


If you are new to NetWare programming, it may seem like there are 
large chunks of information that are missing. Even the excellent 
NetWare Programmer's Guide for C can be problematic for new NetWare 
programmers in that it assumes that everyone knows enough about 
NetWare to dive into a discussion of individual services in the first 


chapter. And itis specifically these kinds of gaps that this book seeks to 
fill in. 


NetWare Programmer’s Guide for C 


This guide is broken down into four sections: 
Directory Services 

Client Services 

Print Server Services 


Transport Services 
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There is a fairly direct correlation between the individual chapters in 
these sections and the service groups identified in Figure 5-2. In some 
cases, service groups are combined into one chapter—e.g., the “Work- 
station Services” chapter discusses connection services, path and drive 
services, and messaging services. 


These chapters in the Programmer’s Guide provide much more “func- 
tional” and “relational” information than can be found in volumes one 
and two of the Client API for C reference manuals. For example, in any 
given chapter the first part of the chapter usually deals with concepts 
necessary to understanding the service calls—like explanations of bind- 
ery objects or Directory Services naming conventions. In some chap- 
ters this is followed by sample code and discussions of specific function 
calls, which help answer the ever present question NetWare program- 
mers face “Which call do I make first?” Finally, at the end of every 
chapter, a “list of functions” is provided with some additional functional 
groupings of calls and some additional call descriptions. 


The Programmer’s Guide also provides an Appendix A which describes 
the data—structures, bit masks, constants, etc.—that is used in the 
SDK. The data is grouped according to chapter and uses section 
numbering that corresponds to each chapter. For example, item 17.9 in 
this appendix describes the semaphore structure used by 
NWScanSemaphoresByName that is described in Chapter 17, “Synchro- 
nization Services.” 


NetWare Client API: Volume 1 and 2 


These two volumes provide the reference for all the NetWare Core 
Protocol (NCP) based calls in the SDK. (The exception to this is the 
addition of the Print Server services calls which are based on IPX and 
SPX.) In previous SDKs, these calls were grouped according to service 
group, but in this SDK the calls are arranged alphabetically with the 
service groupings being provided by an index which is repeated in both 
volumes. Volume one is numbered from 1-654, and Volume two is 
numbered from 657-1094. 


Note: A convenient way to remember the break between the 


two volumes is to remember that Volume two begins with 
the Printer Server services calls that all begin with NWPS. 
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You are strongly 
encouraged, though, to use 
the “2” calls whenever 


possible. 





Occasionally you will run across functions whose names end in the 
number 2. These are improved versions of similarly named functions 
(without the 2), but Novell could not replace the original function for 
reasons of backward compatibility. For example, in earlier versions of 
the OS/2 Developer’s Kits, there was a call name NWGetQueueJobList. 
However, the call was changed to work for 1000-user NetWare. But in 
order to not break existing applications that used this call, the improved 
call was named NWGetQueueJobList2. The old call NWGetQueueJobList 
is not documented in the manual but is exported from the 
NWCALLS.DLL. You are strongly encouraged, though, to use the “2” 
calls whenever possible. 


In addition to a reference of function calls, there are three appendices 
provided at the back of volume two. Appendix A, which was described 
above, contains the error codes or return values for the functions. 
Appendix B contains the structures and declarations used by the func- 
tion calls, and much of this information is similar to Gf not expanded 
upon) in Appendix A of the Programmer’s Guide for C. And Appendix C 
provides a function to function mapping between the older NetWare C 
Interface calls and the current Client API for C calls. This appendix is of 
little use to current OS/2 programmers or OS/2 programmers who 
have used previous OS/2 Developer’s Kits. 


Finally, at the risk of stating the obvious, we need to make a few 
comments about how the reference pages are laid out even though the 
information presented in these pages is, for the most part, very straight- 
forward. 


NetWare Servers 


Most of the calls in the SDK support NetWare 2.2, 3.11, and 4.0 servers. 
In many cases, the calls will even support older servers like NetWare 
2.15 or 3.0; however, because Novell did not test the calls against these 
servers they are not labeled as supported. 


There some calls, though, that are supported only on one NetWare 
server, and you will want to keep an eye on the NetWare Servers 
column to see if you are using one of these calls. For example, all 
Directory Services calls are only supported on NetWare 4.0 while 
NWSaveDirectoryHandle and NWRestoreDirectoryHandle are only sup- 
ported in NetWare 2.2. 
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Finally, you should know that the NetWare Servers column in the Client 
Internationalization manual is meaningless. All the UNICODE 
manipulation and locale manipulation takes place locally on the 
workstation as is completely independent of a NetWare server. The 
indication that these calls will only work with a 4.0 server was probably 
intended to convey that these calls are new to the Client SDK which 
shipped specifically to provide support for NetWare 4.0. 


Client Platforms 


Again, most of the calls in the SDK support DOS, OS/2, and Windows, 
but this is not always the case. The call NWSetInitDrive, for example, is 
only supported on OS/2. 


The area where this single support is most noticeable is in the Client 
Transport Protocol where the IPX and SPX calls are not consistent 
across platforms. For example, [PXCloseSocket with one parameter 
works only with DOS, [pxCloseSocket with a lower case “p” and “x” in the 
name works only in OS/2, and [PXCloseSocket with two parameters 
works only in Windows. (An explanation of why this is the case for IPX 
and SPX is provided in the “IPX and SPX Theory” chapter of this book.) 


Description 


In older Novell SDKs, many of the descriptions provided with function 
calls were merely a restatement of the function call. For example, the 
description for a call like NWDSDuplicateContext might have been 
“Duplicate a directory services context.” And while there is still a lot of 
“restatement” in the descriptions, Novell has made a special effort to 
provide additional, non-obvious information in the description column 
of each function call. 


Syntax 


As mentioned earlier, the variable types used in the documentation are 
the abstract types defined in NWALIAS.H. These types are not neces- 
sarily those used to declare variable types in the actual service group 
header file. 


Parameters 


The convention to be aware of in the parameter descriptions are the 
(IN) and (OUT) tags that precede the description of the parameter. 
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(IN) means that this variable must be declared and set to a certain value 
before making the function call. You are passing this parameter into the 
function. 


(OUT) means that this variable must be declared, but that it’s value has 
no significance until after the function call returns successfully. The 
value for this parameter is coming out of the function. 


Return Values 


In some cases return values are limited to SUCCESSFUL (a value of 
zero) and UNSUCCESSFUL (a negative value). However, many calls 
provide additional return values that you can use to try and make your 
programs more robust. 


Note: The Novell Client SDK provides no equivalent of the 
UNIX errno. 
Remarks 


This is the area you will want to look at to get the more detailed 
explanation of the functions behavior and its parameters. 


Library 


This column tells you which of the libraries or DLLs the function is 
found in. This information can be very useful when you are linking your 
programs. 


Services 


The information in this column tells you what service group the call is 
associated with. This is the “field” that was used to create the index that 
is printed at the back of both volumes one and two. 


See Also 


The calls listed in this column can be several things: they can be calls 
that have similar functionality, calls that need to be made in conjunction 
with this call, or they can identify opposite calls (allocate/free, get/set, 
etc.). Not all calls have See Also entries. 
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NetWare Client Transport Protocol API for C 


This manual is the function reference for all the calls in the SDK that do 
not need a NetWare server to be present. That is, this manual docu- 
ments the transport protocols supported by NetWare. These services 
can still use a client/server model, but the “server” is not necessarily a 
“NetWare server.” 


The following communication services are described in this manual: 
e TLI 
e [PX 
e SPX 
e Diagnostics 
e SAP 
e NetBIOS 
e Named Pipes 


The Programmer’s Guide for C contains overview chapters for these 
services and this book describes these services in its “IPX and SPX 
Theory” chapter. 


There are no appendices to this manual, and the structures provided at 
the end of the manual are nothing more than printouts of the header 
files—they provide no information beyond that. The place to find this 
information is in Appendix A of the Programmers Guide for C. 


Note: Remember that there are separate IPX and SPX calls 
for DOS, OS/2, and Windows. These calls are not “cross- 
platform” as are most of the other calls in the SDK. 


NetWare Client Internationalization API for C 


This manual describes all the calls that the SDK provides to support 
multiple languages. These consist of UNICODE manipulation func- 
tions and locale enabled functions. 
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UNICODE is a double-byte character standard used in all communica- 
tion with NetWare Directory Services. Since OS/2 is usually not set up 
in a mode to display UNICODE characters, you will want to use the 
UNICODE manipulation functions described in this manual to convert 
back and forth between unicode and the current local code page. 


Note: The NetWare Directory Services (NDS) APIs will 
perform the conversions between UNICODE and your local 
code page. If you have no other use for UNICODE aside 
from NDS, you don’t need to worry about using UNICODE. 


The locale functions allow you to manipulate and display monetary 
units, decimal points, dates, and times in a consistent way even if, at run 
time, country code and code page settings vary from machine to ma- 
chine. The following chapter on “Internationalization” gives examples 
of how to design your programs to be easily translated into different 
languages. 


There are no appendices to this manual, and you will want to refer to 
Appendix A in the Programmers Guide for C for additional information 
about the structures and data used by these functions. These are 
described under section 10 “Enabling Services” and section 19 
“UNICODE Services.” 


Additional Documentation you will want to get 


In addition the NetWare Client SDK, you may want to refer to the 
documentation provide with the following additional SDKs: 


NetWare Client SDK for Assembly 
NetWare CLIB SDK 


These SDKs are supplied on the “Promotional CD,” but you may be able 
to purchase printed manual sets by contacting Novell’s Developer 
Relations. 


The NetWare Client SDK for Assembly documents the request and 
reply buffer information for most of the NCPs. While the SDK does not 
document the NCP header information, you will find that the param- 
eters used in the request buffers corresponds amazingly well to (IN) 
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Should the Assembly SDK 
seem of limited use to you, 
we strongly recommend you 
get the CLIB SDK. 


Sample Program: 
WHEREAMI.EXE 


parameters, and that the parameters used in the reply buffers corre- 
spond equally well to (OUT) parameters in Client SDK for C function 
calls. This is because, the NWCalls-style function was designed to a 
large extent as a “pass-through” API to the NCPs. So while the assembly 
SDK is of little direct value to the OS/2 programmer—at least until 
Novell documents the assembly call gate in the OS/2 requester—it can 
provide additional information about parameters and function calls 
themselves. 


For example, it illustrates (and to some degree explains) why the file 
services call NWScanFileInformation2, the subdirectory services call 
NWScanDirectoryInformation2, and the name space services call 
NWScanNSEntryInfo all do the same thing. The function calls are there 
to provide a “pass-through” to three different NCPs. 


Should the Assembly SDK seem of limited use to you, we strongly 
recommend you get the CLIB SDK. Remember, your client workstation 
will be interacting with a server, and the CLIB SDK contains the most 
up-to-date information on what’s happening on the server. It can also 
provide additional information about function calls and parameters that 
are common to both the CLIB and NetWare client SDKs. Different 
groups of engineers and writers documented these SDKs and in many 
cases they provide alternate explanations and descriptions for many 
analogous calls that are contained in the CLIB SDK. 


If you are going to do any NetWare Directory Services programming, 
you will want to obtain from the CLIB SDK is the Directory Services 
Technical Reference. You will find very valuable schema information in 
this manual. 


The sample program describe in WHEREAMI.C is a Client SDK equiva- 
lent of “Hello World.” Itis a relatively simple program that you can use 
to ensure that your MAKE files or your integrated development envi- 
ronment (IDE) is compiling and linking correctly. You will need to link 


with NWCALLS.LIB, NWLOCALE.LIB, and NWNET.LIB. 
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A description of the program is found in Figure 5-5 along with a list of 
simplifying assumptions we made in writing the code. We will follow 
this practice of providing descriptions and simplifying assumptions for 
each sample program throughout the book. 


This program will also be used in the next chapter to illustrate interna- 
tionalization techniques. 


PROGRAM: 


DESCRIPTION: 


SYNTAX: 


REMARKS: 


SIMPLIFYING 


ASSUMPTIONS: 


Figure 5-5. 
Description and 
Simplifying 
Assumptions for 
WHEREAMI.EXE. 


WHEREAMI.EXE 


Displays the name of the server and volume 
where the current drive is mapped. 


WHEREAMI 


If the current drive is mapped with a 
directory services connection, WHEREAMI will 
display your current directory services 
context. 


- If the current drive is a local drive, we 
don’t try to get or display the path. 


e We don’t make any “true” NDS calls; we get 
most of our information from the re- 
quester. 
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As a rule the French rarely approve anything of which they 
have not a model among themselves. 


—G. E. Lessing, Hamburg Dramaturgy 


As the network market expands to other countries, the network applica- 
tion market expands as well. To write an application once and be able to 
sell it in multiple languages increases the potential return on the devel- 
opment investment in an application. Beginning with the NetWare v4.0 
release, all NetWare utilities and system components have been inter- 
nationalized or enabled. This means that the application messages are 
not bound into the application. With the messages separate from the 
application, a set of files can be created and used for many different 
languages without the application being rebuilt. This set of files will 
allow the application to function normally and to output all messages in 
the language chosen by the user. For the purposes of this chapter, a 


ae 





“locale” is a location characterized by a specific set of cultural/social 
conventions such as language, monetary units, and monocasing stan- 
dards. For example, individual locales include the U.S., Great Britain, 
Spain, and Mexico. 


Most applications written in the United States for DOS, and many for 
OS/2 and MS Windows, assume that the ASCII character set in use is 
code page 437 or code page 850. These code pages have assigned 
numeric values to each character available. The assumption of the 
correspondence between a certain numerical value and a certain 
method of rendering that value as a character precludes an application 
from working properly for anyone using a different locale or code page. 
In most compiler implementations, the function call toupper( assumes 
a an ASCII value of 65 (the character “A”) is the upper case version of a 
numeric value of 97 (the character “a”) and that you can subtract 32 to 
get the upper case letter. While this relationship works for most DOS 
code pages for the values from A through Z, the same relationship 
doesn’t apply for the numeric value 134 (the character “a,” an a with a 
circle above it) and 143 (“A,” a capital A with a circle above it). 





To perform the necessary operations for upper casing, sorting, and 
displaying data properly, Novell created a set of tools that draw upon 
the ANSI proposals for localization and on the UNICODE standard 
character sets for internationally enabled applications. The NetWare v4 
operating system is available in English, Spanish, German, French, and 
Italian through the use of these tools. 


Note: While the localization libraries were introduced as 
part of NetWare v4.0, they are not specific to NetWare v4.0. 
They actually run on the client workstation independent of 
any server. 


Levels of Internationalization 





An application can choose from three different levels of internationaliza- 
tion: localization of data, internationalization of data, and full message 
internationalization. These levels deal with local data, shared data, and 
the application’s message interface. 
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Localization of Data 


Internationalization of 
Data 


Message 
Internationalization 


To enable an application to be locale-sensitive, or to properly localize 
data, the developer must be able to handle input and output in the 
workstation’s local code page. Additionally, the display of times, dates, 
and monetary values should also be done according to the locale the 
workstation is configured for. At this level of internationalization, the 
assumption is made that the same workstation that stores the data will 
be retrieving it later. This level of internationalization is sufficient for 
applications that only run locally or on a stand-alone system. 


To enable an application to internationalize data, a developer must store 
and handle the data in such a manner that it can be accessed and 
manipulated by any locale. Additionally, the data will not be signifi- 
cantly changed due to the locale that accessed and manipulated it. The 
NetWare v4.0 Directory Service stores data using the UNICODE 
standard character encoding scheme. Using UNICODE to manipulate 
and store the data in the NetWare Directory allows applications running 
in one locale to manage data in another locale without any threat to data 
integrity. 


Message internationalization implies the application is able to display 
messages in a local form, rather than requiring the application to be 
rebuilt for every locality that is to be supported. The application uses 
message files and offsets into the file in order to determine which 
message to display. “Messages,” in this context, refers to any text that 
appears on the screen where it is a complete sentence or a field label or 
a screen title. 


Each of these levels of internationalization have a set of tools to help the 
application developer enable the code to function properly. Some of the 
tools will eventually be provided by compiler vendors. Until that time, 
Novell provides these tools as part of the NetWare Client International- 
ization API for C. Figure 6-1 lists the tools and which SDKs supply 
them. 
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Figure 6-1. 
Internationalization 
Tools for NetWare 
Applications. 









P| Locale Tools | UNICODE Tools | Message Tools 
NLM SDK Yes Yes Yes 






Which Level to Support 





When designing an application that will be used in international mar- 
kets, you need to decide what level of internationalization you are going 
to support. For some applications, the only internationalization that is 
necessary consists of translating the messages to the user to the lan- 
guages of the countries where the application is going to be sold. 
Another company may distribute an application that keeps all the mes- 
sages in English, but display money, dates, and time in the local format. 
Another company, like Novell, may have a large percentage of their 
market overseas and will have an overriding market reason for enabling 
all software to support locale-sensitive information as well as multi- 
lingual sharing of data. The method best for your application will 
depend on these three factors: 


Where it will be marketed, 


Whether there is any stored data that needs to be localized for 
display, or 


Whether the data will be shared by individuals or offices that do not 
share the same language or locale. 


Localization Functions 





The localization tools for NetWare consist of a set of functions based 
upon the proposed ANSI standard for locale-sensitive calls and a set of 
standard character and string manipulation functions that have been 
constructed to be locale-sensitive and multi-byte aware. These func- 
tions can be found in Figures 6-2 and 6-3. 
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Figure 6-2. New 
Locale Functions. 





NWCharType 





NWCharUpr 







NWCharVal 






NWIncrement 












NWLlocaleconv 







NWLmblen 





NWLsetlocale 






NWLstrftime 






NWLstrxfrm 






NWNextChar 






NWPrevChar 








NWstrlmoney 
NWstrmoney 











Description 





Returns a number indicating if the character passed in is a single- 
byte or multi-byte character. 


Returns the uppercase version of the character passed to the function. 
The uppercasing is done according to the locale-specitic uppercase 
rules. 


Returns the integer value in the local code page of the character 
pointed to. 


Increments the string pointer by the number of characters indicated 
by numChars. 


Returns a pointer to a fully populated LCONV structure. The LCONV 
structure contains the locale specific information that can be queried 
from the workstation. 


Indicates how many characters are in the string pointed to, rather 
than the number of bytes returned by strlen. 


Sets the values identitied by the category variable to values 
appropriate for the locale requested. 


Formats a string according to the locale conventions from the time 
supplied. 


Transforms the input string into a collation sequence based on the 
collation rules defined for the workstation locale. 


Increments a char pointer to the beginning of the next logical locale- 
specific character regardless of the number of bytes per character. 


Decrements a char pointer to the beginning of the last logical locale- 
specific character regardless of the number of bytes per character. 


These functions create locale-formatted strings of monetary values 
from numbers. 
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The functions in Figure 6-3 consist of the ANSI equivalents that have 
been made locale-sensitive. These functions will use the information 
provided by the operating system to properly manipulate strings and 
characters in the workstation locale. 


Fancion | Deseipion 


NWatoi These functions are all enabled to properly understand 

NWisalnum multibyte characters. However, in 

NWisalpha double-byte environments, all double-byte characters 

NWisdigit are assumed to be alphabetic characters. 

NWLstrehr These functions are locale sensitive and multibyte 

NWLstrcoll enabled. They assume a character to be a logical 

NWLstrcspn unit and query the workstation for its size. 

NWLstrpbrk 

NWLstrrchr 

NWLstrrev 

NWLsérspn 

NWLstrstr 

NWLstrupr 

NWstrncoll 

NWstrncpy 

NWstrnum 

NWorintf These functions are internationalized to allow message strings 

NWeprintf to be translated. When strings are translated, 

NWsprintt the grammar changes order and often parameters 

NWvéprintt must be reordered. If you precede the first parameter 

NWvprintf delimiter in a string (e.g., %x) with an order delimiter 

NW sprintf (e.g., %1%x), then these functions will place the variable 
Figure 6-3. Localized NWwsprintf length parameter list members in the appropriate locations in 


Standard String and 


Character Functions. translated strings. 
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Figure 6-4. ANSI 
Proposed Localization 
Functions. 


NWLlocaleconv 





Proposed ANSI Locale Functions 


In the ANSI C proposal, several functions have been included to make C 
locale-sensitive. These functions include llocaleconv, lmblen, lsetlocale, 
Istrftime, and Istrxfrm. What each of these functions do is listed in 
Figure 6-4. The Novell equivalents of these functions differ slightly 
from the ANSI definition. The LCONV structure has additional mem- 
bers added to it that are not in the proposed ANSI definition. The 
character pointers in the LCONV structure have been replaced by 
arrays for proper functionality in the various client environments. 


Function Description 
llocaleconv Queries the workstation to determine which locale is being used and what 


conventions are used in the locale for displaying dates, times, money, 
and decimal numbers. 


Imblen Returns how many characters are in a string even if an individual 
character is rendered using more that one byte. 


Isetlocale Enables an application to change the locale on the workstation. 


Istrftime Formats time strings according to locale conventions. 


Istrxfrm Transforms strings so that they can be properly collated for the collation 
conventions used in the locale. 





The NWLlocaleconv function is used to populate the LCONV structure 
and initialize the locale information in the library. The LCONYV struc- 
ture (Figure 6-5) is allocated by the application and the address passed 
to the NWLlocaleconv API. The various fields in the structure are set so 
that the application can use this information to properly format num- 
bers, money, fractions, time, and dates when they are found in strings. 
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If the function returns a pointer that is set to NULL, there was an error 
in setting the locale information. This call also returns the code page 
and country ID as part of the structure. These values can be used to call 
NWInitUnicodeTables discussed in the next section. 


typedef struct Lliconv 

{ 
char decimal_point[4]; 
char thousands_sep[4]; 
char groupingL4]; 
char currency_symbol[4]; 
char mon_decimal_point[4]; 
char mon_thousands_sep[4]; 
char mon_groupingl8]; 
char positive_signl4]; 
char negative_sign[4]; 
ehar iAtuTracaigits: 
char Trac_digits: 
char p_cs_precedes; 
char p_sep_by_space; 
char n_cs_preceds; 
char n_sep_by_space; 
char p_sign_posn; 
char n_sSign_posn; 
/* Novell Additions to the ANSI definition:*/ 
int code_page; 
int country_id; 
char data_list_separator[2]; 
char date_separator[2]; 
char time_separator([2]; 
char time_format; 
int date_format; 
char am[MERIDLEN]; 
char pm{—MERIDLEN]; 


char reserved[4]; 
Figure 6-5. Definition j LCON\: 
of LCONV Structure. 
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NWLmblen 


NWLsetlocale 


Figure 6-6. Locale 
Categories and the 
Information Affected. 


The NWLmblen API is for determining the number of characters in a 
string rather than the number of bytes. This function call allows a 
string to be made up of any number of single- and/or double-byte 
characters. The length returned is not to be confused with the number 
of bytes in the string. The number of bytes will not correspond to the 
number of characters if the string has any double- or multi-byte charac- 
ters in it. 


The NWLsetlocale API allows the application to initialize the locale- 
sensitive information for the given locale. Ifthe locale variable is set to 
NULL, the function will return a pointer to the country ID string. The 
country ID string is a three-digit string that is the international country 
telephone dialing prefix for the locale. The category variable in the API 
will determine what information is set. If the value of category is 
LC_ALL, all locale-sensitive machine information is set to the locale 
specified. Otherwise, the information only set for the specified catego- 
ries. The categories are defined according to Figure 6-6. Be careful not 
to use any information not set if you don’t use the LC_ALL category. 
For example, if you use LC_CTYPE as the value of category, you will 
always be able to query the character type and know that is set up for 
the locale you specified. However, the time format, date format, and 
collation sequence values will still be set to values that relate to the 
locale that was in effect before you made the call to NWLsetlocale. 


LC_TIME Time formats in NWstrftime and LCONV 
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NWLstrttime 


Figure 6-7. | Format- 
ted Time Values and 
What Information is 

Formatted. 


NWLstrxfrm 


Internationalization of 
Data 


The NWLsirftime function will return a formatted time string for the 
locale and/or the length of the formatted time string. If the string 
variable is NULL, only the length of the formatted time string is re- 
turned. This API will format the string with the information in the 
timeptr structure, which is of the ANSI standard type tm, according to 
the format specified by the format parameter. The format parameter 
can be one of the values found in Figure 6-7 which also specifies what is 
returned for each value. 


Format Value Information Affected 







The NWLstrxfrm API transforms a string into its collation values. This is 
particularly useful if the application has several strings that need to be 
collated or sorted relative to each other. The use of this call in 
conjunction with the use of the styemp function on the transformed 
strings will allow an application to decrease the processing time need to 
compare strings (especially when compared to the time required to use 
multiple iterations of the NWLstrcoll API). The string is transformed 
from the input string, stving2, to the collation values in the output string, 
string1. When two transformed strings are compared, the values being 
compared are the collation values. 


The internationalization of data occurs when the data can be stored, 
accessed, and manipulated by several locales without changing the data 
values unintentionally. The Novell tools for internationalizing data are 
based on UNICODE. UNICODE is a 16-bit character encoding scheme 
that allows all locales to be able to store, access, and manipulate the 
same data without causing corruption due to the locale-specific 
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datapoint definitions. UNICODE data may not always be displayable on 
the workstation doing the work, but it can be manipulated programmati- 
cally. Data stored using UNICODE ensures that every character has a 
unique value in every locale. 





UNICODE Functions 





The functions found in Figure 6-8 include functions for initializing and 
accessing UNICODE character tables and for manipulating UNICODE 
strings and characters in ANSI equivalent UNICODE calls. The ANSI 
equivalent calls are straightforward in their use, but some of the other 
calls require more explanation. 


rein Ton 


NWFreeUnicodeTables These functions are used to 
NWGetCollationHandle load and unload the necessary 
NWGetLocalToUnicodeHandle UNICODE table in memory. 
NWGetMonocaseHandle 

NWGetUnicodeToLlocalHandle 

NWInitUnicodeTables 

NWLoadRuleTable 

NWUnloadRuleTable 


NWLocalToUnicode Converts a character’s numeric value from 
the local code page value to the UNICODE 
numeric value. 


NWUnicodeCompare Compares two UNICODE characters using 
their numeric values. 


NWUnicodeToCollation Converts a UNICODE character to its 
corresponding collation value using the 
UNI_COL.xxx table from memory. 





Figure 6-8. UNICODE- 
enabled Funciton 
Calls. 
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inion 


NWUnicodeToLocal Converts a UNICODE character to its local 
code page equivalent. If the local code page 
doesn’t support the character, the nomap 
value is returned. 





NWUnicodeToMonocase Monocases a UNICODE character to its 
UNICODE monocase according fo the rules in 
UNI MON.xxx. 
unicat These functions (unixxxxx) 
unincpy perform the same operations 
unirev on UNICODE strings that their 
unichr C-runtime string (strxxxxx) 
uninicmp equivalents perform on ASCII 
uniset strings. The one exception is 
unicpy unisize which corresponds to 
uninset the sizeof macro in C. 
unisize 
unicspn 
unipbrk 
unispn 
uniicmp 
unipcpy 
unistr 
unilen 
unirchr 
Figure 6-8. unitok 
ustcotenabi | gina 
(Continued) 
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NWnitUnicodeTables 


Figure 6-9. Naming 
the UNICODE Tables. 


Figure 6-10. Finding 
the UNICODE Tables 
on the Network. 


The NWInitUnicodeTables function call will load the four rule tables for 
the specified codePage and countryID. These tables function for con- 
verting from the local code page character to the UNICODE character, 
converting from the UNICODE character to the local code page charac- 
ter, monocasing a string (similar to uppercasing), and collating strings. 
These tables are named according to the rules in Figure 6-9 and are 
searched for according to the information in Figure 6-10. 


UNI_<codePage>.<countryID> 
<codePage>_UNI.<countryID> 
UNL COL.<countrylD> 


UNI_MON.<countryID> 


The NWInitUnicodeTables API determines what tables should be loaded 
and then calls NWLoadRuleTable for each of the four tables, followed by 
NWGetCollationHandle, NWGetLocalToUnicodeHandle, NWGet- 
MonocaseHandle, and NWGetUnicodeToLocalHandle. 


LL; Check the current directory. 
i Check the load directory. 


-P Check the NLS directory as a child of the load directory 
or a sibling of the load directory 


Check the DPATH and PATH environment variables. 
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NWFreeUnicodeTables 


NWLocalToUnicode and 
NWUnicodeToLocal 


NWUnicodeCompare 


NWwUnicodeToCollation 


NWuUnicodeToMonocase 


The NWFreeUnicodeTables API will call NWUnloadRuleTable for each 
of the four rule tables loaded in NWInitUnicodeTables. This call must be 
made by an application before termination if the NWInitUnicodeTables 
call is ever made. 


The NWLocalToUnicode and NWUnicodeToLocal API calls will convert 
a character between the local code page and the UNICODE encoding. 
If the character will not map to the local code page, then the functions 
will use the character supplied in the moMap variable to indicate a 
character without an equivalent. Typically, these calls should only be 
made when getting input and output from the user. A character 
converted from the local code page to the UNICODE encoding and then 
back will lose information from the original. 


The NWUnicodeCompare API will compare two characters after they 
have been converted using the NWUnicodeToCollation function. If this 
function call returns a positive value, then the chr1 variable comes after 
the chr2 value in an ascending collation. The opposite is true if a 
negative value is returned. Ifthe function returns 0, than the characters 
are equal in collation value. 


The NWUnicodeToCollation function will convert a UNICODE string to 
a UNICODE collation string. A nomap character is placed in any 
location where the UNICODE character has no value in the collation 
table. This is similar to the NWLstrxfrm function in the localization 
tools. After a string has been converted to a collation string, it can be 
compared using the NWUnicodeCompare function. 


Monocasing is the process of suppressing the case differences in a 
string. This is accomplished by either converting the string to all upper 
case characters or to all lower case characters. How the string is 
converted depends on the monocase table for the country being used. 
Converting a string to its monocase is useful before collation of a set of 
strings that will be displayed. Typically, the case of a character is not 
significant to the collation sequence. This, however, differs from lan- 
guage to language. 
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Message Internationalization 





The Novell tools for extracting messages from the source code, creat- 
ing a message database that can be translated, and creating a message 
file for the application are supplied with the NLM SDK. 


With the MSGEXTR.EXE tool an existing application can remove any 
literal message strings currently in the source. These message strings 
are replaced with a defined value. This value corresponds to a defined 
message. When the application uses the NWLOCALE print functions 
with these message tags, the messages the print functions will retrieve 
from an external message file. This message file can contain messages 
in any natural language and can be dynamically loaded at run time. 


A new application can use the same scheme and avoid the message 
extraction step by placing all messages in a text file to begin with and 
referencing them with message tags. The message text file is converted 
to amessage database. Asa step in the build process, the message tags 
are converted to the address of an array member by using another tool, 
the MSGEXP.EXE. Full details on these and other tools and their uses 
are available with the NLM SDK. 


This book does not require the use of the message tools and will not use 
them in any of the sample programs. Other tools from other vendors 
exist for message internationalization, and each developer will need to 
use the tools that best suit their development environment. 


The next chapter will cover some of the necessary steps to enable an 
application to deal with localized and internationalized data using the 
localization and internationalization tools provided in the Client SDK 
from Novell. 
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re 
ae 








To continue with the German genders: a tree 1s male, its buds 
are female, its leaves are neuter; horses are sexless, dogs are 
male, cats are female,—Tomcats included, of course; a person’s 
mouth, neck, bosom, elbows, fingers, nails, feet, and body, are 
of the male sex, and his head 1s male or neuter according to the 
word selected to signify 1t, and not according the sex of the 
individual who wears it,—for in Germany all the women wear 
either male heads or sexless ones. 


—Mark Twain, A Tramp Abroad 


To demonstrate the steps you need to keep in mind for internationaliz- 
ing your application, we are going to take the application from “The 
NetWare Client SDK for C” chapter, WHEREAMI.EXE, and interna- 
tionalize it. Although we will not use every internationalization function 
call available, the discussion will focus on the requirements for properly 
and completely internationalizing an application running in a NetWare 
environment. The simplifying assumptions we made when writing this 
sample application are detailed in Figure 7-1. 
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PROGRAM: LOCALE.EAE 


DESCRIPTION: Queries the workstation for locale 
information, initializes to use the 
UNICODE tables, and demonstrates how to 
use the parameter reordering 
Functionality in the NetWare printf 


Functions. 
SYNTAX: LOCALE 
REMARKS: The LOCALE.EXE program simply takes the 


WHEREAMI program from the introduction 
to the SDK and enables or 
internationalizes it. 


SIMPLIFYING 

ASSUMPTIONS: « The workstation has been installed 
with the requester and the UNICODE 
tables are available in the 
\OS2\NETWARE directory where the 


requester and libraries are also 
Figure 7-1. Descrip- installed. 
tion and Simplifying 
Assumptions for 
LOCALE.EXE. 


Initialization 





There are three types of internationalization: localization of date, inter- 
nationalization of data, and message internationalization. We will dis- 
cuss the mechanics of using the functions provided by Novell to inter- 
nationalize your data and localize your application interface. For the 
third level, internationalizing your messages, you will need to get the 
message tools provided with the NetWare NLM SDK. 


The utilities provided with the NetWare v4.0 operating system have 
been localized to present data in the.appropriate local formats for the 
national language support chosen by the user. This localization is done 
by using the NWLOCALE library and the message tools created by 
Novell. To use the NWLOCALE.DLL in the OS/2 environment with the 
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Borland C++ compiler, you must remove two objects from the library 
that are built using the Microsoft C compiler. To remove these object 
modules, you will need to use TLIB.EXE (or the library manager 
provided with your compiler) with the command lines: 





TLIB nwlocale.lib -vfprintf 
TLIB nwlocale.lib -fprintf 


in an OS/2 window. After removing these objects, the libraries will link 
properly with your application, but you won’t have access to the interna- 
tionalized file write support of any of the fprintf type calls. 


First, to determine the country code and code page that your worksta- 
tion is configured for, make a call to NWLlocaleconv to initialize the 
library’s internal variables and query the system for system localization 
information (Figure 7-2). Using the information from this call, you can 
in turn initialize the NWNET.DLL by calling NWInitUnicodeTables and 
passing in the values for JIconvBuffer.country_id and 
lconvBuffer.code_page (Figure 7-3). Directory services will not properly 
translate strings from UNICODE strings to local code page strings 
unless this call has been made. 


void NWPTR varPtrs[5]; 
¥a__|1StSLack: 
LCONV lconvBuffer, NWPTR JIconvPtr= NULL; 


|lconvPtr=NWLlocaleconv(&lconvBuffer); 


if (lconvPtr!=NULL) 
{ 

/* Remember that the stack in NWLOCALE is sixteen bit, so set 
it up that way by indicating the size of our 32-bit args 
to be longs in the format string using 4041d (can’t use 
L) or by fitting the 16-bit variables in one variable */ 

/* The next 4 lines force longs, note that the stack starts 1 
long before the variables and the variables are in the 
Same order as the format string */ 


' myLong = (UINT32)]lconvBuffer.code_page; 
Figure 7-2. Sample 
Code for Initializing myLong &= QxOQOOFFFF; 
aLocale Information. 


Internationalizing Your Applications 95 


// zero out the 
high order word 
varPtrs[3] =(UINT32 NWPTR)myLong; 
myLong = (UINT32)1lconvBuffer.country_id; 
myLong & OxXOOOOFFFF; // zero out the high 
order word 
varPtrs[4] = (UINT32 NWPTR)myLong; 
Va_Start( stack, varPtrs(l2]); 
NWvprintf( “Your code page is 4041d and your 
country ID is 4041ld\n”, stack); 
va_end(stack); 


/* The next 3 lines put 16-bit values in the right order in 
one 32-bit value. Note again that the stack starts 1 
long before the variables and the variables are in the 
Same order as the format string with the first value 
in the low order word for INTEL */ 

myLong = (UINT32)1convBuffer.country_id; 

myLong <<= 16; 

myLong |= lconvBuffer.code_page; 

varPtrslL4] = (UINT32 NWPTR)myLong; 

va_start(stack, varPtrs[3]); 

NWvprintf( “Your code page is 404d and your 
country ID is Z204d\n",. stack): 

va_end(stack) ; 


Figure 7-2. Sample 
Code for Initializing 
Locale Information. 

(Continued) 


If you use statically defined values as parameters for the 
NWInitUnicodeTables function, you have no guarantee that the result- 
ing string will contain characters that are displayable on the PC where 
the application is running. This initialization function is responsible for 
finding, opening, and reading the UNICODE tables for conversion 
within the local code page. These tables include a code page to 
UNICODE mapping, a UNICODE to code page mapping, collation 
sequence rules, and monocasing rules. As an alternative, you can call 
NWLoadRuleTable for each of the UNICODE tables, then use the 
NWGetxXxXTableHandle calls to get handles to all the tables to be used 
for subsequent function calls that require the rule handle. 
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Figure 7-3. 

Sample Code for 
Initializing UNICODE 
Functionality. 


void NWPTR varPtrs[5]: 
Va_liStstack: 
LCONV lconvBuffer, NWPTR IconvPtr= NULL; 


lconvPtr=NWLlocaleconv(&lconvBuffer); 


if (lconvPtr!=NULL) 
{ 
myLong = (UINT32)]lconvBuffer.code_page; 
myLong & QOxOOOOFFFF; // zero out the high 
order word 
varPtrs[3] =(UINT32 NWPTR)myLong; 
myLong = (UINT32)1lconvBuffer.country_id; 
myLong &= OxOOOOFFFF; // zero out the high 
order word 
varPtrs[4] = (UINT32 NWPTR)myLong; 
Va Start(stack, varPtrslz]): 
NWvprintf( “Your code page is %404ld and your 
country ID is Z2041d\n”, stack); 
va_end(stack); 


myLong = (UINT32)1lconvBuffer.country_id; 

myLong <<= 16; 

myLong |= IconvBuffer.code_page; 

varPtrs[4] = (UINT32 NWPTR)myLong; 

VaStartistack, VvarPtrs 3): 

NWvprintf( “Your code page is £04d and your 
country ID is 204d\n”", stack): 

va_end(stack); 


ccode =NWInitUnicodelTables(lconvBuffer.country_id, 
lconvBuffer.code_page); 
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String Manipulation 





The localized versions of the string manipulation calls work the same as 
the standard versions of the same calls. However, it is essential that you 
make the call to NWLlocaleconv before using any of the localized string 
functions. This call is responsible for detecting which language and 
character set your machine is configured for and to set up internal 
variables with that information, including whether the system is using a 
single byte or multi-byte character set. 


The UNICODE versions of the string manipulation functions also work 
like their standard counterparts. In order for them to work, you must 
first call NWInitUnicodeTables so that the character mapping tables for 
UNICODE and the local code page are loaded in memory where they 
can be used properly by the function calls. 


Any of the ANSI-standard string manipulation function calls that do not 
have localized equivalents do not interpret the character in any way. 
For this reason, they don’t need localized equivalents. 


Output and Parameter Reordering 





The most significant change in the behavior of any of the function calls 
that were created to function with a multi-lingual awareness involves 
the printf calls. These calls were changed to support the necessary 
parameter reordering that occurs when a message is translated into 
another language. Many languages follow different syntax rules for the 
placement of nouns, verbs, and adjectives within sentences. These 
rules more often than not causes a shifting in the order of the variables 
passed to output functions like printf, sprintf, and vprintf. 


Two steps must occur for your application code to be independent of the 
languages supported. First, the strings must be removed from the 
source files, placed in a text or message file, and referenced indirectly. 
The best way to do this first step is to either have a message array that 
is initialized when your application starts up and reference all the 
messages by their address in the array or to use the Novell Message 
Tools. The message tools are shipped as part of the NetWare NLM 
SDK. This SDK is optional for writing your client applications and a 
discussion of the message tools is beyond the scope of this book. The 
use of these tools is treated well in the documentation of the NLM SDK. 
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Second, all format specifiers must be preceded by an argument list 
order specifier. For example, in the sample in Figure 7-4, the message 
string contains the arguments in a different order, but the argument 
themselves are passed in the same order on both calls to NWuprintf. 
This allows the strings to be translated with the parameters being 
reordered in the string but remaining in the same order in the function 
call in the source code. 


myLong = (UINT32)]lconvBuffer.country_id; 

myLong <<= 16; 

myLong |= lconvBuffer.code_page; 

varPtrs[4] = (UINT32 NWPTR)myLong; 

WA_StariLt stack, VarPtrs(3]>: 

NWvprintf(“This string has 2 items, #1: %1%d and 
#2: %eedyn”, stack): 

NWvprintf( “You can print them the other way too, 
#2: %2%d and #1: 41%4d\n”,stack); 

va_end(stack); 

return( Success) 


Figure 7-4. Parameter 
Reordering Sample 
Code. 


In creating the sample code for this book, we learned a couple of things 
about the behavior of the NetWare print calls. To use the standard 
library version of vprintf, you call va_start with the last parameter on the 
stack (Figure 7-5). However, when using NWvprintf, you need to call 
va_start with va_list and the address of the array element which is 
numbered one less than the first array element that you used (Figure 
7-6). In the sample code, the varPtrs array allows us to create a pseudo 
stack of parameters to pass to the va_start call. 
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Figure 7-5. Using 
vprintf(). 


Figure 7-6. Using 
NWyprintf() with 
String Pointers. 


Figure 7-7. Using 
NWsprintf() and 
NWprintf() Together. 


varPtrsl4] = 
va_Start(stack, 
vorintft( “2s”, 
va_end(stack); 


varPtrsl4] = 
va_start(stack, 
NWvprintf(“%s”, 
va_end(stack); 


With the Borland C++ Compiler, there is a problem declaring C variable 
parameter calls in “extern C” sections of the header files. When the call 
is used twice with different argument lists, the compiler decides there 
are multiple definitions. So, NWprintf in the sample (Figure 7-7) can 
only be used with one parameter after it is used that way once and the 


same with NWsprintf. 


NWsprintf(msgStr, 


(void NWPTR)fullPath; 
varPtrs[3]): 
Stack); 


(void NWPTR)fullPath; 
varPtrs[3]): 
stack): 


“Your NetWare location is %s\n”, 


(char NWPTR)fullPath); 


NWprintf(msgStr) ; 
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To create strings with multiple parameters, you have two choices. You 
can do it the hard way by making multiple calls to NWspvintf with string 
fragments and concatenate the fragments, and then call NWprintf. Or, 
you can do it the easy way and use the NWupvintf call. You can get the 
compiler to accept calls with variable parameter lists by making 
separate declarations for each way that you use it, but then you must 
declare the functions outside of a “extern C” section. This will work fine 
if you are building all the code for such a function call yourself. This 
won’t work with the NWLOCALE.LIB during the link because of the 
name mangling that occurs so that the symbol in your code doesn’t 
match the symbol exported in the library. 


Internationalization of your application isn’t difficult, it just requires a 


little planning and a change in the way you are accustomed to putting 
output messages in the source code. 
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Objects and groups, bearings, faces, reminiscences... 


—Walt Whitman, Leaves of Grass 


The NetWare Bindery 





The bindery is a simple, special-purpose, flat-file database. NetWare 2 
and 3 use the bindery to store information about users, print queues, 
and other network objects. NetWare 4 can be (and typically is) set up so 
that bindery APIs continue to work as if the file server had a bindery. 
This is known as “bindery emulation.” For a more complete discussion 
of bindery emulation refer to chapter two of the “Getting Started” 
manual in the NetWare 4 documentation set. 
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The components that make 
up the bindery are objects, 
properties, and property 
values. Objects are at the 
highest level. The bindery 
can be viewed as a set of 
objects. Objects can have 
properties, properties can 
have values. 


The files that make up the bindery are stored in the file server’s 
SYS:SYSTEM directory. For NetWare 3 and 4, bindery data is stored in 
three files called NETSOBJ.SYS, NETSPROP.SYS and NETSVAL.SYS. 
For NetWare 2, there are two files called NETSBIND.SYS and 
NETSBVAL.SYS. Most programs, however, do not need to deal with 
the bindery at the file level. In fact, the bindery files are flagged as 
nonsharable hidden and system files, and NetWare keeps the bindery 
files open and locked to prevent direct access by any method other than 
the bindery APIs. Software like backup programs that need to access 
the bindery files directly can call NWCloseBindery to close the bindery 
before reading the files. 


The primary purpose of the bindery is to provide a secure database of 
information about network objects that the NetWare server software 
can use. Most programs that access the bindery, therefore, are network 
management utilities. However, NetWare provides APIs to make the 
bindery extensible by your programs. Because access to the bindery is 
controlled by NetWare’s security features, your programs can use the 
bindery to store small amounts of data relating to network objects, for 
which read and write access must be controlled. 


Bindery Components 





The components that make up the bindery are objects, properties, and 
property values. Objects are at the highest level. The bindery can be 
viewed as a set of objects. Objects can have properties, properties can 
have values. Figure 8-1 shows a conceptual view of a bindery with a few 
objects. 
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Object: COSTA-GAVRAS 
TYPE: File Server 


Property: NET_ADDRESS 


Value: COEDBABE:001EF239 










Property: OPERATORS 


Value: Set of Bindery IDs 
Property: ACCOUNT_SERVERS 















Object: Supervisor 
Type: User 


Value: Account balance data structure 

















Value: Set of bindery IDs Value: Login Control data structure 





Object: HP_LASER 
Type: Print Queue 


Property: Q_SERVERS 








Object: GUTENBERG 
TYPE: Print Server 






Value: Set of Bindery IDs 


Property: Q_USERS 


Property: NET_ADDRESS 






Value: COEDBABE: 1E1BOFF2 





Value: Set of Bindery IDs 
Property: Q_OPERATORS 
Property: Q_DIRECTORY 
Value: Directory path 


Value: Set of Bindery IDs 


Figure 8-1. 
Conceptual View of 
the Bindery. 


Bindery Objects , 


Each object has a number (the object ID), a name, and a type. Each 
object can be uniquely identified either by its object ID, or by its name 
and type. It is permissible to have bindery objects of different types 
with the same name. For example, it is not uncommon to have a print 
queue and a print server with the same name. 


As we discussed in the chapter “The NetWare Client SDK for C,” 
bindery IDs and some of NetWare’s other internal data items can cause 
confusion because they are declared in the “big-endian” (Sometimes 
called high-low) byte order. We use the same format as the SDK header 
files, but you should be aware that you may see references in Novell 


documentation to file servers being bindery object type 4, even though 
NWBINDRY.H declares OT_FILE_SERVER as 0x0400. 
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Static and Dynamic 
Objects 


One purpose of dynamic 
objects is to make it easier 
to locate objects on the 
network. 


All objects in the bindery are either static or dynamic. Static objects are 
written in the file server’s bindery files and remain in the file server’s 
bindery until a program explicitly deletes them. When you use the 
SYSCON utility to create a user, the utility creates a static user object in 
the file server’s bindery. Whenever you bring up the file server, that 
server object will be in its bindery, until you delete the object. 


Dynamic object are temporary, and are stored in memory while the file 
server is running. They are primarily used to point to the location of 
objects elsewhere on the network. A file server adds dynamic objects to 
its bindery as it becomes aware of them, typically via the Service 
Advertising Protocol (SAP). 


When a file server is brought up, its bindery contains only the static 
objects that have been written to the server’s bindery file. The server 
sends out a broadcast packet to find out what other file servers exist on 
the network, and as responses come in, the server creates dynamic 
objects for each file server that responds. As other network services 
(like advertising print servers) use SAP to announce their presence on 
the network, the file server adds other dynamic objects to the bindery 
for each service. When the file server is shut down, all dynamic objects 
are released from memory. The set of available dynamic objects will be 
rebuilt again when the server is brought up. 


There is one static file server object in the bindery of every bindery- 
based NetWare file server. On file server QUAHOG there will be a static 
file server object named QUAHOG that has properties that hold 
accounting charge information. These properties are discussed later in 
this chapter. 


Most dynamic objects just have one property, called NET_ADDRESS, 
whose value is the network address of the object. For example, if a 
network has two file server, ITCHY and SCRATCHY, server ITCHY will 
have a dynamic file server object in its bindery for server SCRATCHY. 
The object will have one property called NET_ADDRESS, whose value 
is the network address of server SCRATCHY. 


One purpose of dynamic objects is to make it easier to locate objects on 
the network. To find a file server, you can build an IPX broadcast packet 
(assuming you are using the IPX protocol on your network), send it out 
on the network, and see if the file server you are looking for responds. 
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Or you can look for a dynamic file server object in the bindery of a file 
server you are attached to. Ifthe file server you are looking for is in the 
bindery of the file server you are attached to, you can then get the 
network address of the file server (or other object) you are looking for. 


Object Properties 


Properties of an object are used to store data associated with the object. 
Properties can have values associated with them. Values are data stored 
in 128-byte segments. Although it is possible for a property to have no 
value, properties nearly always have at least one data segment. 


There are two types of properties: item properties and set properties. 
Item properties can contain data of any type. For example, a user’s 
ACCOUNT_BALANCE property contains a 4-byte account balance, a 4- 
byte credit limit, and 120 bytes of zeroes. 


Set properties contain a series of 4-byte bindery ID numbers. A user’s 
GROUPS_I’M_IN property contains the bindery IDs of all the user 
groups the user belongs to. To read the IDs from a set property’s 
segment, treat the segment as an array of unsigned longs. Read from 
the beginning of the segment until you reach a bindery ID of 0x0000. It 
is possible for a property to have more than one data segment, so you 
may have to call NWReadPropertyValue more than once to get all the 
bindery IDs in a set. 


Bindery objects and properties have a one-byte value associated with 
them that determines the security level associated with the object or 
property. There are five security levels, and each object or property has 
separate security level values for reading or writing. Figure 8-2 explains 
the five security levels. 
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Yan [ew [Bein 

Anyone Access allowed to any client, even 
if they are not logged in to the 
file server. 

Logged Access allowed only to clients who are logged in to 
the file server. 

Access allowed only to clients who are logged in as the 
object, or are security equivalent to the object. 

Supervisor Access allowed only to clients 
logged in as SUPERVISOR or 
equivalent. 

4 


Bindery Access allowed only to the operating system. 














Figure 8-2. Bindery 
Security Levels. 





The high-order nibble of the security access byte specifies the write 
access level; the low-order nibble specifies read access. So, for ex- 
ample, if NetWare’s accounting feature has been installed on a file 
server, each user has an ACCOUNT_BALANCE property. The security 
byte for the property is set to 0x32, meaning that only the supervisor 
can set a user’s account balance, but any object logged in to the file 
server can read it. 


If read access is set to 4, your programs will not be able to read the 
property, and you will have to take our word for it that the property 
actually exists. This is the case with the PASSWORD property. For 
obvious reasons, NetWare doesn’t want you reading or writing the 
password property directly (even if you are SUPERVISOR, and even 
though the passwords in them are encrypted). Instead, the NetWare 
operating system handles all the situations that involve reading or 
writing the PASSWORD property. The operating system provides APIs 
for setting and changing passwords. 


108 OS/2 and NetWare Programming: Using the NetWare Client API for C 


Figure 8-3. Bindery 
Object Types Defined 
in NWBINDRY.H. 





Well-known Bindery Object Types 





Novell maintains a registry of well-known bindery object types, to 
prevent confusion when network services use SAP to advertise their 
existence. If you want to market an application that uses SAP to 
advertise its services, you should contact Novell’s Professional 
Developer’s Program for information about having a bindery object 
type assigned. Figure 8-3 shows the bindery object type values defined 
in NWBINDRY.H. 



























Value 
Bindery Object Type | Hex Decimal 
OT WILD 
OT UNKNOWN 0 
OT PRINT QUEUE 768 
OT FILE_SERVER 1024 
OT JOB SERVER 1280 
OT_GATEWAY 1536 
OT_ARCHIVE_SERVER 2304 
OT ADVERTISING PRINT SERVER 18176 


OT_PRINT_QUEUE_USER 0x5300 21248 
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The wild object type (-1) is used when calling NWScanObject to scan for 
objects of any type. The purpose of the unknown object type (0) is a 
mystery, and an object of that type has never been observed in nature. 


There are actually many more Novell-defined object types than those 
defined in NWBINDRY.H. A more complete list is presented in Figure 
8-4. This list was gathered empirically, and is not guaranteed to be 
complete nor accurate. 


Object Bindery Object Type Value 
-] or OxFFFE (OT_WILD) 

User 0x0100 (OT_USER) 

User 0x0200 (OT_USER_GROUP) 

00300 (OT_PRINT_ QUEUE) 

0x0400 (OT_FILE_ SERVER) 

0x0500 (OT_JOB_ SERVER) 


Gateway 0x0600 (OT GATEWAY) 
Print Server 0x0700 (OT PRINT SERVER) 
Archive Queue 0x0800 (OT ARCHIVE QUEUE) 


Archive Server 0x0900 (OT ARCHIVE SERVER) 


Job Queue 0x0A00 (OT_JOB QUEUE) 

Administration 0x0B00 (OT ADMINISTRATION) 

NetBIOS 0x2000 

NAS SNA Gateway 0x2100 (OT_NAS_SNA_GATEWAY) 
0x2300 


Remote Bridge Server 0x2400 


Bridge Server 0x2600 (OT_REMOTE_BRIDGE_SERVER) 


Figure 8-4. Bindery 
Object Types. TCP/IP Gateway 0x2700 (OT _TCPIP_GATEWAY) 
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Figure 8-4. Bindery 
Object Types. 
(Continued) 


Eicon X.25 Point-Point 
Gateway 


Eicon 3270 Gateway 


Time Synchronization 
Server 


Archive Server Dynamic 
SAP/SMS TSA 


DI3270 Gateway 
Advertising Print Server 
Micom Interlan TCP/IP 
Gateway 

Btrieve VAP v5.x 
NetWare SQL 

Xtree Network Version 
Btrieve VAP v4.x 

Print Queue User 
ARCserve VAP 


Eicon X.25 Multipoint 
Gateway 


ARCserve 3.0 
WANcopy Utility 

TES - NetWare for VMS 
Emerald Backup 
NetWare Access Server 
Portable NetWare 


Progress DB Server 





Bindery Object Type Value 


0x2800 


0x2900 


0x2D00 (OT_TIME_ 
SYNCHRONIZATION_ SERVER) 


0x2E00 
(OT_ARCHIVE_SERVER_DYNAMIC_SAP) 


0x4500 


0x4700 
(OT_ADVERTISING_PRINT_SERVER) 


0x4800 


0x4B00 

0x4(00 

0x4D00 

0x5000 (OT_BIRIEVE_VAP) 
0x5300 (OT_PRINT_QUEUE_USER) 
0x5500 

0x5800 


0x6600 
0x7200 
0x7A00 
0x9200 
0x9800 
0x9E00 
0x9F00 
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Bindery Object Type Value 





PowerChute NLM (old) 0xA100 
Compag IDA Status 0xAC00 
Monitor 
Intel LAN Protect 0x201 
Oracle DB Server 0x301 
RSPX 0x701 
Novell SNA Gateway OxF01 
HP Print Server 0x1201 
(SA MUX 0x1401 
(SA LCA 0x1501 
(SA CM 0x1601 
(SA SMA 0x1701 
(SA DBA 0x1801 
(SA NMA 0x1901 
(SA SSA 0x1A01 
CSA STATUS 0x1B01 
CSA APPC 0x1E01 
SNA TEST 0x2601 
(SA TRACE 0x2A01 
Communications 0x3001 
Executive 
NNS Domain 0x3301 
NNS Profile 0x3501 
Bindery Objet Trees, | MNS Queue 0x3701 
(Continued) 
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Figure 8-4. 
Bindery Object Types. 
(Continued) 









Bindery Object Type Value 





NNS Domain Scheme 0x3801 
Descriptor 






Intel LANSpool VAP 0x4101 






Aladdin Knowledge 0x4201 
IrmaLAN Gateway 0x5201 






Intel PICKIT/CAS 0x6801 
Talk Server 






Compag SNMP Agent 0x7401 













0x8001 





Xtree Server 






0x8901 
GARP Gateway 0xB001 







BindView 0xB101 
NMA Agent 0x3302 






LANZ Agent 401F NetExp 0x3702 






0x3802 






LANZ Agent 4800 





NMS Hub Management 0x3902 
LANZ Agent 401F 0x3A02 






NMS Console 0x6A02 









NetWare 4 Time 0x6B02 
Synchronization Server 






NetWare 4 NDS Server 0x7802 










NetWare for SAA Gateway 0x403 





0xA03 






Gallacticom BBS 






HP Laserjet 0x03 





Attachmate 3270 Gateway 0x2003 


Bindery Services Theory 113 





Bindery Object Type Value 


PowerChute v3.0 0x7E03 
ViruSate Notify 0x7F03 
HP Bridge 0x8603 

0x8703 
Lotus Notes 0x9B03 
Certus Anti Virus NLM 0xB703 
ARCserve 4.0 0x(403 
Intel LANSpool 3.5 0x(703 


Lexmark 4033 Print 0xD503 
Server 


NetWare SQL/Gupta 0xDE03 
NLM 


UnixWare 0xE103 
UnixWare 0xE403 
SiteLock Anti-virus 0x2904 


SiteLock Checks 0x2005 


SiteLock Checks 0x2905 


SiteLock 0x290B 
SiteLock Applications 0x290C 
LAI SiteLock 0x8023 
Meeting Maker 0x8(23 
Figure 8-4. 
Bindery Object Types. SiteLock Server 0x0848 





(Continued) 
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Figure 8-4. Bindery 
Object Types. 
(Continued) 


For some bindery objects to 
operate correctly, they must 
have a specific set of 
properties. For example, a 
user cannot log in tf the 
user’s bindery object doesn’t 
have a PASSWORD 


property. 


Rabbit 3270 Gateway 


Intel NetPort 0x0280 


WordPerfect Network 0x8888 
Version 


SiteLock 0x1 FFI 





Well-known Bindery Properties 


For some bindery objects to operate correctly, they must have a specific 
set of properties. For example, a user cannot log in if the user’s bindery 
object doesn’t have a PASSWORD property. Other properties are only 
required if a particular feature of NetWare is in use. For example, if 
accounting is installed, user objects must have an 
ACCOUNT_BALANCE property, or the user will not be able to log in. 
Your programs can add additional properties to bindery objects, but the 
properties described in this section are used by the NetWare operating 
system. 


Some well-known bindery properties are described in the figures be- 
low. Each property is described in detail after the figures. Under bind- 
ery emulation in NetWare 4, objects appear to have a number of proper- 
ties in addition to those we discuss here. We recommend that you use 
directory services functions, rather than bindery functions, to manipu- 
late these properties. 
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User Properties 


Figure 8-5. User 
Properties. 


Figure 8-6. 
USER_DEFAULTS 
Property. 


User Group Properties 


Figure 8-7. 
GROUP_MEMBERS 
Property. 


Figure 8-5 describes the properties of the user object. 


Security Security 
GROUPS I’M IN Logged 










In addition, one specific user object, SUPERVISOR, has a 
USER_DEFAULTS property, which is described in Figure 8-6. 


Property Type Write Read 
Security Security 










Figure 8-7 shows the property, GROUP_MEMBERS, associated with 
user group objects. 





Property Type Write Read 
Security Security 
GROUP_ MEMBERS Static SET Logged 
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Server Properties Figure 8-8 shows well-known properties of server objects. 
Write 


Security Security 
Static Set Server 
Static Item Server 
Static Item Server 


Type 

























Static Item Server 
Static Item Server 
Static Item Server 
Dynamic Item Bindery 
Static Set Supervisor 


Figure 8-8. Properties 


Supervisor 
of Server Objects. 


Static Item 


Queue Properties Figure 8-9 gives information about properties of queue objects. The 
example program INSTALL.C in the chapter “A Queue Management 
Services Sample Application” illustrates how to create a queue object 


and its properties. 
Security Security 


Q_USERS Static Set Logged 


Type 















Figure 8-9. Properties 
of Queue Objects. 
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ACCOUNT BALANCE 


ACCOUNT_HOLDS 


ACCOUNT_SERVERS 


ACCT_LOCKOUT 


User objects have an ACCOUNT_BALANCE property when accounting 
is installed on a file server. Contains two long (4-byte) values, the 
account balance and credit limit. If the credit limit value is negative, the 
user is allowed unlimited credit. 


The ACCOUNT_HOLDS property is dynamic; it is created when an 
accounting server places a hold on a user’s account, and deleted when 
the last hold is cleared. The ACCOUNT_HOLDS property is an array of 
16 HOLDS_INFO structures, as declared in NWACCT.H: 


typedef struct 
{ 
DWORD objectID; 
long amount; 
} HOLDS_INFO; 
typedef struct 
| 
WORD holdsCount; 
HOLDS_INFO holds[16]; 
} HOLOS_STATUS: 


If an object ID is zero, that hold entry has been cleared. Only 16 
accounting servers can place holds on a user’s account simultaneously. 


Before a network service (like a job server, or the make server we 
present in the chapter “A Queue Management Services Sample Applica- 
tion”) can charge for services, its bindery ID must be in the file server’s 
ACCOUNT_SERVERS property. The make server’s installation pro- 
gram (INSTALL.C) shows how to call NWAddObjectToSet to add an 
accounting server to the ACCOUNT_SERVERS property. 


ACCT_LOCKOUT contains server settings related to NetWare’s in- 
truder detection feature. The server object has an ACCT_LOCKOUT 
property when intruder detection is enabled. Intruder detection set- 
tings for each user are stored in the user object's LOGIN_CONTROL 


property. 
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BLOCKS READ 


The ACCT_LOCKOUT property contains three 2-byte fields: 
allowedLoginAttempts, resetMinutes, and  lockoutMinutes. 
AllowedLoginAttempts specifies how many unsuccessful login attempts 
a user is allowed before his or her account is locked. resetMinutes is the 
number of minutes without an unsuccessful login attempt that must 
pass before the badLoginCount field in the LOGIN_CONTROL property 
is reset to zero. lockoutMinutes is the number of minutes an account 
will be locked after the number of allowed login attempts has been 
reached. 


The static file server object has BLOCKS READ, BLOCKS_WRITTEN, 
CONNECT_TIME, DISK_STORAGE, and REQUESTS_MADE proper- 
ties when accounting has been installed on the server, and charge rates 
have been set for any of these services. The format of data fields in each 
of these properties are identical, and have the following structure: 


typedef struct { 
BYTE daysChargeOccursMask; 
BYTE timeChargeOccurs; 
WORD chargeRateMultiplier; 
WORD chargeRateDivisor; 

} CHARGE_RATE; 


struct { 
DWORD timeOfNextCharge; 
WORD currentChargeRateMultiplier; 
WORD currentChargeRateDivisor; 


CHARGE_RATE definedChargeRates[20]; 
} CHARGE_PROPERTY ; 


NetWare allows you to define up to 20 charge rates that are applied at 
specified days and times. NetWare uses the first three fields of the 
property to maintain the current charge rate. TimeOfNextCharge is the 
time the server is to apply the next defined charge rate as the current 
rate. 


NetWare calculates charge rates for disk storage differently from the 
other services (see DISK_STORAGE). 
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BLOCKS WRITTEN 


CONNECT_TIME 


DISK_STORAGE 


GROUP_MEMBERS 


currentChargeRateMultiplier and currentChargeRateDivisor determine 
how much the file server is to charge for services performed. To 
calculate how much to charge a user’s account, NetWare multiplies the 
units of service (disk blocks read/written, server requests performed, 
or half-hour periods of connect time) by currentChargekateMultiplier, 
then divides by currentChargeRateDivisor. 


The daysChargeOccursMask and timeChargeOccurs values specify when 
each of the defined charges take effect. One bit is set in the 
daysChargeOccursMask, indicating the day the charge rate takes effect. 
If bit 0 is set, the rate takes effect on Sunday; if bit 6 is set, it takes effect 
on Saturday. TimeChargeOccurs is a value 0-47 that specifies the time of 
day that the new rate takes effect. Zero means midnight, 47 is 11:30 pm. 
At the time the new charge takes effect, NetWare copies the 
chargeRateMultiplier and chargeRateDivisor to the current values, then 
finds the next rate to be applied and sets the timeOfNextCharge field. 


See BLOCKS_READ for the structure of data fields in the 
BLOCKS_WRITTEN property. 


See BLOCKS _READ for the structure of data fields in the 
CONNECT_TIME property. 


See BLOCKS _READ for the structure of data fields in the 
DISK_STORAGE property. 


NetWare calculates the charge for disk storage by multiplying the 
number of disk blocks a user is using by the number of half-hour 
periods since the last disk storage charge was made, multiplying that 
value by the current charge rate multiplier, then dividing by the current 
charge rate divisor. 


GROUP_MEMBERS is a set property of a user group object. It contains 
the bindery IDs of user objects in the group. 


120 OS/2 and NetWare Programming: Using the NetWare Client API for C 





GROUPS I’M_IN 


IDENTIFICATION 


LOGIN_ CONTROL 


GROUPS_I’M_IN is the complement of the GROUP_MEMBERS ob- 
ject. Each user has a GROUPS_I’M_IN property with the bindery IDs of 
user group objects that the user belongs to. 


Contains a string with the full name of the user or group. You can use 
SYSCON to set the full name. 


Contains a large data structure with security settings for the corre- 
sponding user account. The file server supervisor object’s 
USER_DEFAULTS property contains the default values for each field in 
this property. When SYSCON creates a new user object, it copies the 
servers USER_DEFAULTS property to the new _ user’s 
LOGIN_CONTROL property. Structure of the fields in the property is 
as follows: 


struct { 
BYTE accountExpirationDate[3]; 
BYTE accountDisabledFlag; 
BYTE passwordExpirationDate[3]; 
BYTE graceLoginsRemaining 
WORD passwordExpirationInterval; 
BYTE graceLoginResetValue; 
BYTE minimumPasswordLength; 
WORD maximumConcurrentConnections; 
BYTE allowedLoginTimeBitmapLl42]; 
BYTE lastLoginDateAndTimel[6]; 
BYTE restrictionFlags: 
BYTE reserved; 
LONG maximumDiskUsage; 
WORD badLoginCount; 
LONG nextResetTime; 
BYTE badLoginAddress[12]; 

} LOGIN PROPERTY 


AccountExpirationDate is the date the account expires. For each of the 
3-byte date fields; the first byte is the year minus 1900, the second byte 
is the month (1=January); the third byte is the day. If the account does 
not expire, all three bytes are zeroes. 
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AccountDisabledFlag is zero if the account is enabled, OxFF (1) if 
disabled. NetWare checks this value every half hour. If the account is 
disabled, and someone is logged in on the account, the operating 
system sends a broadcast message telling the user to log out. If the 
user has not logged out within five minutes, NetWare clears the user’s 
connection. 


PasswordExpirationDate is the date the password expires. 


GraceLoginsRemaining is the number of times a user is allowed to log in 
with an expired password. NetWare decrements this value each time 
the user logs in with an expired password. When the value reaches 
zero, the user is not allowed to log in. When the user changes his 
password, this value is reset to the GraceLoginkResetValue. 


PasswordExpirationInterval is the number of days between password 
expiration dates. 


GraceLoginResetValue is the total number of grace logins a user is 
allowed before the account is locked. 


MinimumPasswordLength is the minimum number of characters the 
user’s password must have. If this value is zero, no password is 
required. 


MaximumConcurrentConnections is the maximum number of concur- 
rent connections the user is allowed. If this value is zero, the user is 
allowed the maximum number of connections supported by the server. 


AllowedLoginTimeBitmap represents the 336 half-hour periods in a 
week. Bit 0 of byte 0 is midnight to 12:29 am Sunday, bit 1 of byte 0 is 
12:30 am to 12:59 am Sunday, etc. Ifthe bit is set, the user can log in 
during the corresponding period. 


LastLoginDateAndTime is the date and time the user last logged in (in 
DOS date and time format). 


RestrictionFlags has two bit flags: bit 0 is cleared if the user is allowed to 
change his or her password; set if only the supervisor can set the user’s 
password. Bit 1 is set if user must use unique passwords when chang- 
ing the password. If this bit is set, the user object will have an 
OLD_PASSWORDS property. 
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NET ADDRESS 


NODE_CONTROL 


OLD PASSWORDS 


OPERATORS 


MaximumDisk Usage is the maximum number of disk blocks the user is 
allowed to use. If the field is set to OX7FFFFFFF, there is no limit. 


BadLoginCount is the number of unsuccessful login attempts. NetWare 
resets this field to zero when the user logs in successfully, or when the 
number of minutes in the resetMinutes field of the ACCT_LOCKOUT 
property has passed. The operating system sets this field to OxFFFF 
when the account is locked. 


NextResetTime is the time when the badLoginCount field should be 
reset to zero. 


BadLoginAddress is the address of the workstation that made the last 
unsuccessful login attempt. 


Contains the 4-byte network and 6-byte node and socket address of the 
file server (static or dynamic) or other (dynamic) object. When the file 
server comes online it creates the NET_ADDRESS property for its own 
static object. 


Contains a list of network addresses a user can log in from. Each 
address consists of a 4-byte network address and a 6-byte node address. 
A property segment can hold up to 12 addresses, with the last 8 bytes 
unused. Ifthe last segment in the property has less than 12 addresses, 
the list terminates with a zero address. A node address of 
OxFFFFFFFFFFFF means that the user can log in from any address. 


User objects have this property if the user is required to use unique 
passwords when changing passwords (see the vestrictionFlags field in 
the LOGIN_CONTROL property). Contains the last 8 passwords the 
user used (in encrypted form). When the property is first created its 
first (and only) value is the user object’s name. Only NetWare has 
direct read or write access to this property. 


The OPERATORS property contains the bindery IDs of users who are 
file server console operators. 
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PASSWORD 


Q_ DIRECTORY 


Q_ OPERATORS 


Q_ SERVERS 


Q_USERS 


REQUESTS MADE 


SECURITY_EQUALS 


— USER_DEFAULTS 


The PASSWORD property contains the current password in encrypted 
form. Only NetWare has direct read or write access to this property. 


The Q_DIRECTORY property contains the path of directory the Queue 
Management System (QMS) uses to store queue job files. 


The Q_OPERATORS property contains the bindery IDs of user objects 
that are authorized queue operators. Queue operators can delete jobs 
from a queue, change the order that jobs will be serviced, or place holds 
on any job in the queue. 


The Q_SERVERS property contains the bindery IDs of objects that are 
authorized to service jobs in the queue. Programs must login as an 
authorized object before servicing jobs. 


The Q_USERS property contains the bindery IDs of user objects that 
are authorized to add jobs to a queue. 


See BLOCKS READ for the structure of data fields in the 
REQUESTS_MADE property. 


The SECURITY_EQUALS property contains the bindery IDs of objects 
for which the user has security equivalence. 


The USER_DEFAULTS property contains the default settings for each 
field in user object’s LOGIN_CONTROL property. It has the same 
structure as the LOGIN_CONTROL property. 


Bindery APIs 





Figure 8-10 contains brief descriptions of each of the bindery functions. 
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[racine 


NWAddObjectToSet adds the bindery ID of the specified object to a set 
property. 


NWChangeObjectPassword changes a user's password. Both the old and new 
passwords must be passed to the function. 

NWChangeObjectSecurity changes the security access level for an object. 

NWChangePropertySecurity changes the security access level for a property. 


NWCloseBindery closes the bindery, so the bindery files can be 
archived. Although closing the bindery does not 
break existing connections, most file server 
operations will be disabled. 


NWCreateObject creates a bindery object. 


NWCreateProperty creates a property for a bindery object. Use 
NWWritePropertyValue to write data to the property 
after it is created. 


NWDeleteObject deletes a bindery object. 
NWDeleteObjectFromSet deletes a bindery ID from a set property. 
NWDeleteProperty deletes a property of an object. 


NWDisallowObjectPassword adds a password to a user’s OLD_ PASSWORDS 
property, making the password unusable to the user. 


NWGetBinderyAccessLevel returns the security access level of the requesting 
connection. Can be used to tell whether a connection 


Figure 8-10. Bindery is supervisor-equivalent. 


Functions. 
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es 


NWGetObjectDiskSpaceLeft reports whether a user’s disk usage is restricted, and 
if so, returns the number of additional disk blocks the 
user can allocate. 


NWGetObjectEffectiveRights gets an object’s effective rights to a directory. See 
the File System Services chapter for an explanation of 
how to use directory handles and relative paths to 
specify network directories. 


NWGetObjectID returns the bindery ID for an object, given the 
object’s name and type. 

NWGetObjectName returns an object’s name and type, given its bindery 
ID. 


NWisObjectInSet verifies whether a bindery object is a member of a 
set property. 


NWOpenBindery reopens the bindery after it has been closed for 
archiving (by the NWCloseBindery function). 


NWReaaPropertyValue reads a data segment from the specified property of 
a bindery object. The segmentNumber parameter 
specities which data segment to read from the 
property; loop and increment segmentNumber until 
the function returns 0 in the moreSegments 
parameter. 


NWRenameObject renames a bindery object. 


NWScanObject searches the bindery for objects with a specified 
name, which may include wildcards. To find all 
bindery objects that match a wildcard pattern, set the 
objectID parameter to -1 for the first call to the 


Figure 8-10. Bindery function. Loop until the function does not return 0. 


Functions. 
(Continued) 
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ee 


NWScanObjectTrusteePaths returns file server directory paths where a user has 
been granted trustee rights. To get all trustee paths 
for a user, set the sequenceNumber parameter to -] 
for the first call to the function, then loop until the 
function does not return 0. The function requires a 
volume number. Use NWGetVolumeNumber to get a 
volume number from a volume name. 


NWScanProperty scans a bindery object for properties that match a 
specified name, which may include wildcards. To get 
the names of all properties of an object, set the 
searchPropertyName to “*,” and set the 
sequenceNumber parameter to -1 on the first call to 
the function. Loop until the function returns 0 in 
moreFlag. 


NWVerifyObjectPassword verifies whether a user's password is correct. If the 
specified password is not correct, the function takes 
about 3 seconds to return. The delay makes the 
function impractical for dictionary attacks when 
intruder detection is disabled. 





NWWritePropertyValue writes a segment to the specified property of a 
Figure 8-10. Bindery bindery object. 
Functions. 
(Continued) 
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“Have you any objection to my looking at your register?” said 
Holmes. 


—Arthur Conan Doyle, Hound of the Baskervilles 


Scanning the Bindery 


The sample program BINDERY.EXE reads and displays data in the 
bindery. You can use BINDERY to: 


e View the properties of a specified object 
e View the properties of all objects of a specified type 
e Examine a single property of an object 


e Scan the entire contents of the bindery 
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Figure 9-1. 
Description and 
Simplifying 
Assumptions for 
BINDERY.EXE. 


The syntax for BINDERY is shown in Figure 9-1. 


PROGRAM: 


DESCRIPTION: 


SYNTAX: 


REMARKS: 


BINDERY.EXE 


Displays the properties and values of objects 
in the bindery. 


BINDERY objectName [ objectType [propertyName] 
] 


BINDERY takes and object name as required 
input. For example, if you were to enter 


BINDERY BSIMPSON 


all the properties and values of each bindery 
object named BSIMPSON will be displayed. 
BINDERY also accepts wildcard input, so 
entering 


BINDERY * 


will display the properties and values of every 
object in the bindery. You can limit the 
number of objects displayed by adding the 
object type parameter. For example, entering 


BINDERY * 256 


will display all user objects in the bindery 
and their properties. (That is, all objects of 
type 256 which is the user type.) In addition 
you can limit the properties that are displayed 
using the third parameter. For example, 
entering 


BINDERY * 256 IDENTIFICATION 


will display only the IDENTIFICATION property 
of every user object in the bindery. 


130 OS/2 and NetWare Programming: Using the NetWare Client API for C 


Figure 9-1. 
Description and 
Simplifying 
Assumptions for 
BINDERY.EXE. 
(Continued) 


Use numeric values (decimal or hex) to specify 
object types: 


ALL =f UXPFFRFFFE 
USER 256 0x00000100 
USER GROUP 512 0x00000200 
PRINT QUEUE 768 0x00000300 
FILE SERVER 1024 0x00000400 
JOB SERVER 1280 0x00000500 
GATEWAY 1536 O0x00000600 
PRINT SERVER 1792 0x00000700 
ARCHIVE QUEUE 2048 0x00000800 
ARCHIVE SERVER 2304 0x00000900 
JOB QUEUE 2560 Ox00000A00 
ADMINISTRATION 2816 Ox00000B00 
NAS SNA GATEWAY 8448 0x00002100 
REMOTE BRIDGE SERVER 9728 Qx00002600 
TCPIP GATEWAY 9984 0Qx00002700 


TIME SYNCHRONIZATION SERVER 11520 O0x00002D00 
ARCHIVE SERVER DYNAMIC SAP 11776 Ox00002E00 


ADVERTISING PRINT SERVER 18176 0x00004700 
BTRIEVE VAP 20480 Qx00005000 
PRINT QUEUE USER 21248 0x00005300 


SIMPLIFYING 

ASSUMPTIONS: » BINDERY is being run against a 2.x or 3.x 
server or a 4.x server with bindery emulation 
enabled. 


BINDERY is not an ideal program for illustrating how to use bindery 
APIs. It only exercises four bindery APIs (NWScanObject, 
NWScanProperty, NWReadPropertyValue, and NWGetObjectName), and 
only ones that read the bindery. However, BINDERY can be a useful 
tool for bindery programmers. You can use BINDERY to verify that 
your programs are creating objects and properties as intended, and that 
the data you store in property values has the correct format. For 
an example of how to create bindery objects, see the MAKEIT program 
we present in the chapter “A Queue Management Services Sample 
Application.” 
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BINDERY consists of three procedures: main, DisplaySegment, and 
GetObjectTypeName. main parses the command line and has two nested 
loops: one that reads every object from the bindery that matches the 
name specified on the command line (which may include wildcards), 
and one that reads properties of the objects found. DisplaySegment 
displays the data of a property segment in hex and character formats. 
GetObjectTypeName is a big switch statement that converts a bindery 
type value to a string. Source code for BINDERY is given in Figure 9-2. 
Ellipses indicate where we cut out the boring parts. 


/* bindery.c 
Scan objects and properties in a NetWare bindery */ 


fHinclude <stdio.h> 
fHinclude <stdlib.h> 
#Hinclude <string.h> 
#include <ctype.h> 


4Hdefine IS32BIT 
dtkdefine BCPP 
ftinclude <nwcalls.h> 


void DisplaySegment(BYTE *data, NWFLAGS propertyFlags); 
void GetObjectlypeName(NWOBJ_TYPE objectType, char 
*objectlypeName) ; 


NWCONN_HANDLE conn; 


void main(int argc,char *argv[]) 
{ 


NWCCODE ccode, 
ccode2, 
ccode3; 
char *searchObjectName, 
*searchPropertyName; 
WORD searchlype, 
objectlype; 
char objectTypeName[30]; 
NWOBJ_ID objectID; 
char objectName[48]; 
NWFLAGS objectHasProperties, 
dynamicFlag, 
security; 
DWORD sequence; 
char propertyNameL16]; 
ry ax NWFLAGS propertyFlag, 
igure 9-2. 
ps Listing ns ‘ie toca 
BINDERY.C. asValueFlag, 
moreFlag; 
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Figure 9-2. 
Code Listing of 
BINDERY.C. 
(Continued) 


BYTE index; 

BYTE datal128]; 

BYTE moreSegments, 
valuelype; 


/* handle command-line arguments */ 

Switch (argc) 

{ 

Case.2: 
/* only the object name was specified 
make object type and property name wild */ 

searchObjectName=strupr(strdup(argvl1])); 
searchlype=-1; 
searchPropertyName=(char *)malloc(2*sizeof(char)); 
strcpy(searchPropertyName, “*”); 
break; 


case 3: 
/* only object name and object type were specified 
make property name wild */ 
searchObjectName=strupr(strdup(argvLl1l])); 
if (Cargv[2][0] == ‘0’) && ((toupper(argv[2][1])) 
== ‘X’)) 
sscanf(argv[2], “%x”, &searchType); 
else 
searchType= (WORD)atoi(argvL[2]); 
searchPropertyName=(char *)malloc(2*sizeof(char)); 
strcpy(searchPropertyName, “*”); 
break; 


case 4: 
/* the object name, object type, and property name 
were all specified at the command line */ 
searchObjectName=strupr(strdup(argvl1])); 
searchlype= (WORD)atoi(argvL2]); 
SearchPropertyName=strupr(strdup(argvl3])); 
break; 


default: 
printf(“\nusage:BINDERY <objectName> [<objectType>] 
[<propertyName>]\n”); 
printf( “Use numeric values (decimal or hex) to 
specify object types:\n”); 


printf (“ ALL 28d  Ox%08X\n", 
be SLT? 
printf (“ USER 28d  Ox%08X\n”, 
OTLUSER, OTUSER}: 
printf (“ USER GROUP 8d  Ox%08X\n”, 


OT_USER_GROUP, OT_USER_GROUP):; 


A Bindery Services Sample Application 133 


printrt” PRINT QUEUE USER 8d 
Ox%Z08X\n", 
OT_PRINT_QUEUE_USER, OT_PRINT_QUEUE_USER) ; 


/* initialize NWCalls interface */ 

ccode = NWCallsInit(0,0); 

if (ccode != SUCCESSFUL) 

{ 
printf(“Unable to initialize NetWare interface\n”); 
eExiet-1l): 

} 


/* get connection ID of default file server */ 
ccode = NWGetDefaultConnectionID(&conn) ; 
if (ccode != SUCCESSFUL) 
{ 
printf(“Unable to get connection ID\n”); 
exTLt-1): 
} 


/* start scanning the bindery of the default file server for 
objects */ 
objectID = -1L; 
do 
{ 
ccode = NWScanObject(conn, searchObjectName, searchType, 
&objectID, objectName,&objectlype, &objectHasProperties, 
&dynamicFlag, &security); 


iy (ocode == SUCCESSFUL) 


/* print out the object name */ 
printf( “Object: 4s”, objectName) ; 


/* get the object type and print it out */ 
GetObjectTypeName(objectlType, objectTypeName) ; 
printf (“ Type: 4s\n”, objectTypeName) ; 


/* print out values of object flags */ 


if (dynamicFlag == BF_STATIC) 
Princ "\Estatie ns 
else 


printf(“\tDynamic\n”) ; 


printf(“\tRead access: “); 


Fi 9-2. 
Code Listing of if (security & BS_LOGGED_READ ) 
BINDERY.C. printf( “Anyone logged in\n”); 
(Continued) 
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Figure 9-2. 
Code Listing of 
BINDERY.C. 
(Continued) 


else if (security & BS_OBJECT_READ) 
printf(“Object itself\n”); 

else if (security & BS_SUPER_READ) 
printf(“Supervisor\n”); 

else if (security & BS_BINDERY_READ) 
printf( “System only\n”); 

else 
printf( “Anyone attached\n”); 


Orintrl"\twrite access: “); 

if (security & BS_LOGGED_WRITE) 
printf( “Anyone logged in\n”); 

else if (security & BS_OBJECT_WRITE) 
printf(“Object itself\n”); 

else if (security & BS _SUPER_WRITE) 
printf(“Supervisor\n”); 

else if (security & BS_BINDERY_WRITE) 
printf( “System only\n”); 

else 
printf( “Anyone attached\n”); 


/* scan for properties of the object we have found */ 
if (objectHasProperties) 
{ 
Sequence = -1L; 
do 
{ 
ccode2 = NWScanProperty(conn, objectName, 
objectlype, searchPropertyName, &Sequence, 
propertyName, &propertyFlag, 
&propertySecurity, &hasValueFlag, &moreFlag); 
if (ccode2 == SUCCESSFUL) 
{ 
/* print the name of the property */ 
printf(“\tProperty: %s\n”, propertyName) ; 


/* print settings of property flags */ 

if (propertyFlag == BF_STATIC) 
PRINET OW \ENESTatie in” 2: 

else 


printf (“\t\tDynamic\n”); 

printf(“\t\tRead access: “); 

if (propertySecurity & BS_LOGGED_READ) 
printf( “Anyone logged in\n”); 

else if (propertySecurity & BS_OBJECT_READ) 
DPINtT “Ob Jeet itselTin')s 

else if (propertySecurity & BS_SUPER_READ) 
printf(“Supervisor\n”); 

else if (propertySecurity & BS_BINDERY_READ) 
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printft(“System only\n”); 
else 
printf (“Anyone attached\n”); 


printf(“\t\tWrite access: “); 

if (propertySecurity & BS_LOGGED_WRITE) 
printf( “Anyone logged in\n”); 

else if (propertySecurity & BS_OBJECT_WRITE) 
printf( “Object itself\n”); 

else if (propertySecurity & BS_SUPER_WRITE) 
printf(“Supervisor\n”); 

else if (propertySecurity & BS_BINDERY_WRITE) 
printf (“System only\n”); 

else 
printf( “Anyone attached\n”) ; 


/* if the property has a value, get the 
contents of its data segments and print 
them out */ 

if (!hasValueFlag) 
printf(“\t\tProperty has no value\n”); 

else 

{ 
index = 1; 
do 
{ 

/* get the first segment */ 
ccode3 = NWReadPropertyValue(conn, 
objectName, objectType,propertyName, 
index, data,&moreSegments, 
&valuelype); 
if (ccode3 != SUCCESSFUL) 
printf(“\t\tUnable to read property 
value\n”); 
else 
{ 
/* print out the type of segment we 
have (item/set/net address) */ 
if (valuelype == BF_ITEM) 
priner (CW Atitl vem\n” ) : 
else if (valuelType == BF_SET) 
printfr(*.EAtSet in”) s 
else if (valueType == 1) 
printf(“\t\tNetwork address\n”); 


else 
printf(“\t\tUnknown property 
type\n”); 
Figure 9-2. 
Code Listing of 
BINDERY.C. 
(Continued) 
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DisplaySegment(data, valuelype); 
/* if the property value has more than 
One segment, get all of them and 
print out their contents */ 
while (ccode3 == SUCCESSFUL) 
{ 
index++; 
ccode3 = NWReadPropertyValue(conn, 
objectName,objectlype, 
propertyName, index, data, 
&moreSegments, &valuelype); 
if (ccode3 == SUCCESSFUL) 
{ 
DRINntT(*.An Ds 
DisplaySegment(data, valuelype); 
} 
} while (moreSegments && (ccode3 == 
SUCCESSFUL) ): 
} 
Orinthe wa”) 
} 
} while(moreFlag && (ccode2 == SUCCESSFUL)); 
} 
} 
} while (ccode == SUCCESSFUL); 
printT(“That’s all, folks\n")s 


void DisplaySegment(BYTE *data, NWFLAGS propertyFlags) 


{ 


Figure 9-2. 
Code Listing of 
BINDERY.C. 
(Continued) 


NWCCODE ccode; 

int : a 
NWOBJ_TYPE objectType; 

char objectNamel48]; 


NWOBJ_ID objectID; 


if (propertyFlags & BF_SET) 
{ 

/* the property value contains a set of object IDs; 
display the names of the objectIDs listed in the 
property’s value */ 

for (i1=0; 1<128; it=sizeof(NWOBJ_ID) ) 

{ 
objectID=*((NWOBJ_ID *)(datat+i)); 
if (objectID == 0) /* no more object IDs in this 

segment */ 
break; 
else 
{ 
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ccode = NWGetObjectName(conn, objectID, objectName, 
&objectType); 
if (ccode) 
printf(“\tError:GetObjectName: %02X\n”",ccode); 
else 
printf(“\t\tZs\n”,objectName) ; 


} 
} 
else 
{ 
/* display the data in hex and ascii format */ 
for (1=0; 1<128; ) 
{ 
Orie ver ys 
/* display the data in hex format, 
16 characters at a time */ 
for (j=0; j<l6; g++, i++) 
printft("Z02x% “,datali]):; 
printt<( “ ae 2 


/* display the data (the same 16 characters) in ascii format */ 
for (j=0, i=i-16; g<l6; jt, i) 
{ 
if ((dataliJ>31) && (dataLlij<127)) 
printT(“%c”,dataLlil); 
else 
OrincTe”. )% 
} 
printT< xn”); 


void GetObjectTypeName(NWOBJ_TYPE objectType, char 
*objectTypeName) 
{ 
Switch(objectType) 
{ 
case OT_USER: 
strcpy(objectTypeName, “USER”); 
break; 
case OT_USER_GROUP: 
Figure 9-2. strcpy(objectTypeName, “USER GROUP”) ; 
Code Listing of break; 


BINDERY.C. 
(Continued) 
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case OT_PRINT_QUEUE_USER: 
strcpy(objectTypeName, “PRINT QUEUE USER”); 


break; 
default: 
Sprintf(objectTypeName, “%s [%X]”, “UNKNOWN”, 
objectType); 
Figure 9-2. Source 
Code Listing of 
BINDERY.C. 
(Continued) 


Suggested Enhancements 


BINDERY embodies the evil of the command line. Glory and honor 
await the programmer who rewrites BINDERY for Presentation Man- 
ager. It would also be nice if BINDERY decoded the data structures in 
well-known properties and displayed them in a more meaningful format 
than a hex/text dump. 
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“What classes of things have a greater share of pure existence, 
in your judgement—those of which food and drink and condi- 
ments and all kinds of sustenance are examples, or the class 
which contains true opinion and knowledge and mind and all 
the different kinds of virtue? 


—Plato, The Republic of Plato 


It is difficult to know where to start with NetWare Directory Services 
(NDS). Most of the discussions we’ve read about NDS seem to “start in 
the middle” and quickly digress into numbing repetition of the word 
“schema.” So we'll try to start at the beginning, and we’ll promise not to 
use the word schema more than four times. 
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The purpose of this chapter is to give you the fundamental concepts of 
NDS and give you the background necessary to read the next chapter. 
For that matter, this chapter should give you the necessary background 
to read other articles, chapters, or documents about NDS. But if you 
already know about NDS, and you are primarily interested in the pro- 
gramming aspect of NDS, skip to the next chapter which describes how 
to write a simple NDS application. 


Limitations of the Bindery 





By 1990, with an inter-network of over 300 servers at its Provo, Utah, 
site, Novell was bumping up against some of the limitations of bindery 
servers. Storms of RIP and SAP packets (Router Information Protocol 
and Service Advertising Protocol packets) would knock 2.x servers off 
the network and slow 3.x servers to acrawl. Specialized file servers and 
their associated services were getting further and further away in terms 
of “hop count,” and users were having to spend more and more time 
finding shorter routes to critical services—if they could even get to 
them at all. New employees were literally spending days hunting up the 
supervisors of all the servers they needed to access in order to get their 
jobs done. In short, the Novell inter-network was bursting at the seams. 


The first attempt to address some of these problems took the form of 
Network Name Services (NNS). NNS was a naming service which 
grouped servers into “domains.” Information about all the users on the 
servers and their respective rights could be shared by all the servers in 
the domain. In other words, bindery information was distributed across 
a domain of servers. But while NNS succeeded in some respects, more 
than anything else it revealed the need for a paradigm shift in NetWare 
architecture. The bindery could not elegantly support large Wide-Area 
NetWorks (WANs) or “enterprise-wide inter-networks.” NetWare net- 
works needed something more. 


So Novell bolstered its engineering effort on the NetWare Directory 
Services. Novell targeted NDS to be part of the next major release of 
the NetWare operating system following NetWare 3.11. By doing this, 
Novell would not only alleviate its internal inter-network problems, but 
also of anticipate the needs of customers with inter-networks which 
were growing ever larger and ever more complex. 
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No Server is an Island | 


One way to look at the problem is to imagine a network of bindery 
servers as an group of independent island states. If you were a citizen of 
one these islands and were to travel to a neighboring island, you would 
be required to establish your identity, your right to visit, and a place of 
residence before being allowed onto that island. Once you are on the 
island you could then get information about local attractions, services, 
and resources. However, the only information you could get about 
other islands would be their location. And if you were to visit another 
island you would again have to establish your identify, right to visit, and 
place of residence before being allowed on that island because none of 
the islands know anything about who you are on any another island nor 
will any island communicate information about you to anyone else. And 
while this kind of political organization may have a certain Caribbean 
charm, it is, nonetheless, fraught with inefficiencies. 


Clearly, if the freedom loving peoples of the islands were to unite 
themselves into a single organization, they could offer their citizens 
greater access to the resources of the islands as a whole. In such a 
unified organization, your identity could be authenticated once, and 
then shared with any island that needed to know what resources and 
services to make available to you. In addition, instead of just providing 
you with the location of other islands, you could get information about 
all of the resources available on all of the islands. This is essentially 
what NDS does for NetWare servers. 


All You Need to Know About NDS 





All you need to know about NDS can be summed up in three essential 
concepts: directory partitions, directory objects, and directory names. 
Once you understand these three things, you can “talk the talk” and 
“walk the walk” with any NDS guru. 
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Figure 10-1. The 
Workstation Cannot 
Access Services on 
Server A Because Its 
Link with the Central 
Server is Down. 





Directory Partitions : 


If you are attempting to unify a bunch of bindery servers, one of the first 
decisions you have to make is where to physically keep the information. 
With bindery servers, the bindery information is kept in files in the 
SYS:SYSTEM directory. So one solution would be to collect all the 
bindery files from all the servers and store them on one of the servers. 
However, if this central server went down or became unavailable (be- 
cause of excessive network traffic or political unrest) little if any work 
could get done. Figure 10-1 illustrates how a workstation could have a 
connection to a server but be unable to access its services because the 
central server went down. 
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In NDS, though, the 
physical equivalent of a 
“bindery” became a 
“partition.” Some NDS 
purists may take exception 
to that last statement, but 
an NDS partition is the 
closest thing there is to a 
bindery. 


Another problem with this solution is that servers that are further away 
from the central server in terms of hop count get authorizations much 
slower than closer servers. Consequently, the decision was made to 
physically distribute the “authorization information” across the entire 
network. In this way, the network could not only keep functioning in 
the event that servers went down, but also users at distant locations 
could get faster authorizations. 


Again, the information that needs to be distributed in NDS is essentially 
the same information that was stored in the bindery: users and their 
rights, print queues and the users who have rights to use them, etc. In 
NDS, though, the physical equivalent of a “bindery” became a “parti- 
tion.” Some NDS purists may take exception to that last statement, but 
an NDS partition is the closest thing there is to a bindery. And you could 
set up an NDS tree so that each server had its own partition and was a 
self-contained unit (i.e. an organizational unit, but we haven’t gotten to 
those yet). This sort of tree structure would be functionally equivalent 
to a group of NetWare 3.x servers. To gain the advantages of NDS, you 
would need to make copies of each of the partitions and put them on the 
other servers in the group. (However, we realize that this is not the 
most efficient organization for all—or even many—cases.) 


A copy of an NDS partition is called a replica, and the original partition 
itself is called the “master replica.” In addition to being copiable, 
replicas are also changeable. That is, if a partition is copied as a Read/ 
Write replica, an administrator can change the replica at its remote 
location and these changes will find their way back to the original 
partition or master replica. Partitions can also be copied as Read-Only 
replicas which can be used as “backup” replicas or as a way to speed up 
a remote user’s access to the partition information. 


For example, Figure 10-2 shows how a workstation can read an alter- 
nate partition if the “master” partition is unreachable. The partition that 
contains information about User A is on NDS server #1, but a connec- 
tion to server #1 is unavailable. However, user A can still login to the 
NDS tree (at NDS Server #2) because a replica of the partition that 
contains information about User A can be found on NDS server #4. 


This partitioning scheme has some implications for server installation. 
When installing a server, you must specify what context you are install- 
ing the server at. If you install in a new Organizational Unit (or OU), 
install creates a new partition, then creates a read/write replica on the 
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server with the root partition (or master partition). If you install into an 
existing Organizational Unit, install asks you if you want a read/write 
replica on the server you are installing. However, there are two prob- 
lems with the default partitioning scheme in NetWare: 1) the root 
server may hold a lot of read/write replicas, which could affect its 
performance, and 2) there is no replica of the root partition unless you 
install a second server at the root context. 
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Figure 10-2. User A 
Can Access Services 
in the NDS Tree 
Because a Replica of a 
Partition Exists on 
NDS Server #4. 


The NetWare Client API for C provides APIs that let you add, join, split, 
remove, and list partitions on an NDS network. There are also APIs that 
let you add, change, purge, and remove replicas of partitions in the NDS 
tree. For a detailed discussion of these APIs, refer to chapter 4 of the 
NetWare Programmer’s Guide for C. 
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Inheriting Attributes 


In NDS, all objects in the 
tree inherit attributes from 
the “Top” class. 


NDS Class Definitions 





Directory Objects | 


Once you've decided on where to keep the information, the next deci- 
sion you need to make is how you are going to organize it. Willit bea 
big database? And if so, how will the database be structured. For NDS, 
Novell engineers decided to put all the bindery-like information into 
NDS objects. NDS objects are similar to bindery objects to a degree, 
but where bindery objects in NetWare 3.x were mostly analogous to 
“things,” objects in NDS are better understood in terms of object- 
oriented paradigms. So bear with us while we briefly try to show how 
NDS was influenced by object-oriented design. 


One way to create something is to duplicate something that already 
exists. For example, suppose we wanted to create a ball, we could look 
at a ball that already exists and make a ball just like it. Our new ball 
would have the same shape as the original ball, the same color, and 
probably even be named the same thing. In this sense, then, we could 
refer to “shape,” “color,” and “name” as attributes of a ball. And since a 
“ball” is generally round (ignoring football and rugby for the moment), 
we might even say this: “shape” is a mandatory attribute of a ball, and 
the “shape” attribute must have a value of “round.” To state things in 
more NDS-like terms, we would say that shape is a mandatory attribute 
of an object inheriting from the object class “ball.” (Now you know why 
NDS is so confusing.) 


Now, just for fun, let’s look at our ball from a classical perspective. In 
ancient Greece Plato argued that “real” objects existed only in the mind 
of God and that everything we see around us is a shadow of those “real” 
forms. For Plato, the objects of our world inherited attributes from the 
“pure” or “real” forms, but these attributes (as well as their values) were 
distorted shadows of the real form. We bring all this up because a pure 
form for Plato is the NDS equivalent of the “Top” class. In NDS, all 
objects in the tree inherit attributes from the “Top” class. 


Before we go any further, we need to distinguish between the terms 
“object” and “class” since many NDS discussions use these words 
interchangeably. Think of class as being the rules for making objects, 
and think of objects as the things that are made by following the rules. 
Objects are, then, instances of classes. So, going back to the Top, every 
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object in the NDS tree takes part of its form from the rules specified by 
the Top class. And Top has only one mandatory rule: every object in the 
tree must have an attribute named “Object Class.” This means that any 
object you create in the NDS tree will have an attribute of “Object Class” 
which can be set to the appropriate value: user, queue, volume, etc. 


At this point, let’s abandon the ball example and work through the 
example of the user class. As a user on an NDS network, you would 
probably have a network address, a home directory, and a login script. 
As it happens, these are all attributes of the object class “User.” How- 
ever, if you were to look at the specification of the User class, you’d see 
that CN (common name) and OU (organizational unit) are not at- 
tributes of this class. So where does all that OU and CN stuff you see all 
the time in NDS come from? It comes from “higher” classes or super- 
classes that class User inherited from. 


If you were to look at the NDS specification some more, you’d see that 
“Organizational Person” is a super class of object class “User.” In other 
words, “User” inherited all the attributes of “Organizational Person.” 
And an optional attribute of “Organizational Person” is OU (organiza- 
tional unit). You’d also see that “Person” is a super-class of “Organiza- 
tional Person.” In other words, “Organizational Person”—and conse- 
quently “User”’—inherited all the attributes of “Person.” And a manda- 
tory attribute of “Person” is CN (common name). Finally, “Top” is a 
super-class of “Person,” and “Person” inherits all the attributes of “Top.” 
Figure 10-3 makes all this less confusing by illustrating the hierarchial 
nature of this object inheritance. And the complete specification of 
inheritance and mandatory and optional attributes is found in the 
NetWare Directory Services Schema Specification. 


There are also a number of APIs in the SDK that allow you to create, 
read, and modify classes and their attributes. 
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TOP 
Mandatory Attribute=Object Class 















Person 
Mandatory Attribute=CN 


Organizational Person 
Optional Attribute=OU 


User 


Inherited Attributes: Object Class=User 
CN=AHAB 
OU=PEQUOD 


Optional Attribute: Home Directory=SYS:USERS\AHAB 


Figure 10-3. Inherit- 
ance of USER Object 
from Super Classes. 


Access Control Lists Another good example of inheritance in NDS is the access control list 
(ACL). When a system administrator grants you access to an object in 
the NDS tree, your rights to that object are stored in the object itself. 
Your rights are stored as values in the ACL attribute of the object which 
it inherited as an optional attribute of the Top class. In addition to rights 
a system administrator may explicitly grant you, you also inherit any 
rights you may have had to a parent object. For example, if you were 
given SUPERVISOR rights to a server object, you would also inherit 
SUPERVISOR rights to any volume objects on that server. 
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For a more complete discussion of the implications of inheritance, refer 
to the “NetWare Security Theory” chapter in this book. 


Creating Objects Once all the rules for making objects have been defined, you can begin 
to make objects. The first object that gets created during a NetWare 4.x 
installation is the Root object which is created using the rules of the Top 
class. You don’t actually create the Root object, the install program 
creates it for you. However, you do get to create the next level of 

Some of the NetWare gbjects, which are called container objects. They are called container 
utilities will break if they objects because they can “contain” other objects. 

encounter a Country object. 

Container objects are created using the class definitions of Country, 
Locality, Organization, or Organizational Unit. These class definitions 
are also hierarchical to a certain extent. For example, a country object 
can only exist below the root object, but an organization object can exist 
either below the root object or a country object. (Be aware that some of 
the NetWare utilities will break if they encounter a Country object.) 
Figure 10-4 illustrates three NDS trees which use different container 
objects. Consequently, in the rest of this chapter we’ll only refer to the 
WHEELS_WORLD tree. 


Note: When we get to the concept of “context” you will want 
to remember that a context is made up of the names of 
container objects. Or it might be easier to consider context 
as a path through an NDS tree. 


At the bottom of the object hierarchy are the leaf objects. These are 
objects like Users, Volumes, Print Queues, etc. They do not “contain” 
other objects, and have no subordinate objects. APIs to add, read, 
modify, and delete objects in the tree are provided in the SDK. 
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Figure 10-4. Three 
NDS Trees Showing 
the Use of Container 
Objects. 


Naming Leat Objects, 
or What About Bob 


Root 


Country=US Country=CH Country=GB 
Organization=TIRES_A_US 


Organizational Unit=MFG Orgainzational Unit=SALES 


Root 
Country=US Country=GB 
Locality=LONDON 
Organization=WE_ARE_WHEELS 


Organizational Unit=SALES Organizational Unit=MFG 


Root 
Organization=WHEELS_WORLD 
Organizational Unit=>WW_USA Organizational Unit=>WW_SWITZERLAND 


Organizational Unit=MFG Orgainzational Unit=SALES 





Directory Names 


With partitions we answered the question of where the NDS informa- 
tion would be kept. With objects we answered the questions of how the 
organization would be organized. Now we'll tackle the question of how 
to label these objects. And we’ll start with leaf objects. 


Leaf objects have a common name or CN associated with them. For 
example, a user could have a CN of CN=BOB. However, a print queue 
could also have a CN of CN=BOB. Since NDS does not require common 
names to be unique at any given level in the tree (i.e. any particular 
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Naming Container 
Objects 


Context Handles 


context), more information is needed to determine what BOB is. We 
get this information by looking at the value of the object class attribute. 
The value of the object class attribute of user BOB is USER, and the 
value of the object class attribute of print queue BOB is QUEUE. 
(Future versions of NDS may require all common names at a particular 
level, or context, to be unique.) 


In alarge NDS tree it is possible that you could have more than one user 
object with the name BOB. In order to eliminate any ambiguity about 
which BOB we want to use, we can specify a particular BOB by identify- 
ing all the container objects between BOB and the Root. When you put 
all the container objects names together you have an NDS “context.” 
Referring back to Figure 10-4, user BOB in the MFG organizational unit 
would have a common name of CN=BOB and a context of 
OU=MFG.OU=WW_USA.O=WHEELS_WORLD. In this example, 
CN=BOB is considered a partial name or a relative distinguished name 
(RDN) because it requires a context of some sort to make it unique in 
the tree. The “full” name for BOB’ would be 
CN=BOB.0OU=MFG.OU=WW_USA.O=WHEELS_WORLD. A full name 
is also called a distinguished name (DN) in NDS. (Don’t confuse “full 
name” with “typeful name” which we'll discuss in a moment.) 


When you log in to a directory tree, the client requester reads your local 
NET.CFG file and tells NDS the default context of your user object. 
That is, it tells NDS what container objects exist between you and the 
root. But since string manipulation can be slow, the design of the NDS 
APIs require you to call NWDSCreateContext, which allocates a numeri- 
cal handle that NDS can resolve to your current context. 


When you call NWDSCreateContext you create a context handle that not 
only indicates a location in the tree, but also provides information to all 
the NDS APIs that require a context handle. The additional information 
that is supplied in the context handle (as well as default values) is listed 
below: 
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DCV_CANONICALIZE_NAME=T RUE 
DCV_TYPELESS NAMES=TRUE 
DCV_DEREF_ALIASES=TRUE 
DCV_XLATE_STRINGS=TRUE 
DCK_CONFIDENCE=CDV_LOW_CONF 


The value of DCV_CANONICALIZE_NAME tells the NDS APIs 
whether they need to append a context to the names coming in or if they 
the names coming in are already full names. The value of TRUE tells 
the NDS APIs to append a context to all names. 


The value of DCV_TYPELESS_NAMES tells the NDS APIs whether 
they should report their results (i.e. output values) in typeless names or 
in typeful names. The value of TRUE tells NDS APIs to convert results 
to typeless names. We'll discuss typeless names some more in a 
moment. 


The value of DCV_DEREF_ALIASES tells the NDS APIs how to work 
with aliases. A value of TRUE tells the NDS APIs that they should not 
use the alias but rather find the original object (i.e. de-reference the 
alias) and perform all their operations on the original object. And we'll 
discuss this a little bit later on too. 


The value of DCV_XLATE_STRINGS tells the NDS APIs whether they 
should translate strings from UNICODE to your local code page. A 
value of TRUE tells the NDS APIs they should convert all UNICODE 
strings to your local code page before returning, and a value of FALSE 
tells the NDS APIs to leave the strings in UNICODE. 


The value of DCK_CONFIDENCE tells the NDS APIs whether they 
should query nearby replicas for information or if they should get their 
information from master replicas. A value of CDV_LOW_COMF tells 
the APIs to use locally cached information or information from the 
nearest replica. CDV_HIGH_COMF tells the APIs they must use infor- 
mation from master replicas. 


If you want to change any of these values then you can call 
NWDSSetContext with the desired parameters and then allocate a new 
context handle using NWDSCreateContext. Any context handles that 
you allocated earlier will still retain their original values, but the new 
context handle will have the values you set in NWDSSetContext. Refer 
to volume one of the API reference for specifics about using this call. 
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Leading and Trailing 
Periods in a Context 





When You Can’t Find 
Objects 


If for some reason, you don’t want the NDS APIs appending a context to 
the names of your objects, you can override their natural inclination to 
do so by putting period in front of the common name of your object. For 
example, the leading period in the name .CN=BOB.OU=MFG.OU= 
WW_USA.O=WHEELS_WORLD tells the NDS APIs to ignore the cur- 
rent context and just use the full name as it is. 


A name with a trailing period tells the NDS APIs to remove the left- 
most organizational unit (or least significant organizational unit) from 
the current context before appending it to the name. For example, if 
you were take the full context CN=BOB.OU=MFG.QU=WW_ 
USA.O=WHEELS_WORLD and were to break off CN=BOB.OU=MFG, 
it would leave OU=WW_USA.O=WHEELS_WORLD as the remaining 
portion of the context. But if you were to add a trailing period to the first 
part—CN=BOB.OU=MFG.—it would tell the NDS APIs to remove the 
left-most, or least significant organization unit from the remaining 
context. In this case OU=WW_USA would be removed and the resulting 
context would be CN=BOB.OU=MFG.O=WHEELS_WORLD. Two 
trailing periods would tell NDS to remove the two least significant 
organizational units from the context. 


Note: Don’t put leading or trailing periods in the context you 
set in your NET.CFG file. Also remember that a name can’t 
have both leading and trailing periods. 


Sometimes the NDS APIs won’t be able to find an object that you know 
is in the tree. These instances will usually be the result of your 
specifying an incorrect name/context combination. If you should en- 
counter this kind of error, try making the same NDS call again with a 
different context. For example, in the ATTACH.C sample code provided 
in the “Connection Services Sample Application” chapter of this book, 
we make a call to NWDSLogin using the context provided by the NDS 
API NWDSCanonicalizeName. If the call fails, we call NWDSLogin 
again, only this time we use the context of the server we are currently 
attached to. 
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Typeless Names and 
Typeful Names 


Aliases 


Mandatory Setup and 
Cleanup 


Using NDS Buffers 


Going back to our BOB example, the string CN=BOB would be consid- 
ered a typeful name because the “CN=” part of the name provides 
information about what type of object BOB is. A typeless name for the 
user BOB might look something like this: 


BOB.MFG.WW_USA.WHEELS_ WORLD 


If you do not want to use typeless names you can call NWDSSetContext 
and set DCV_TYPELESS_NAMES to FALSE. 


Any object in NDS can have an alias. Referring yet again to our example 
of BOB, you could create an alias object for BOB—named, let’s say, 
BILLY_BOB—at the context of OU=WW_SWITZERLAND.O= 
WHEELS_WORLD. You could then read and manipulate this alias as if 
the original BOB object were really at the 
OQU=WW_SWITZERLAND.O= WHEELS_WORLD context. However, 
on “write” operations, the NDS APIs will de-reference the alias and 
operate on the original object BOB object at its original context. 


RG CT es Ce 


At this point, we’ve covered the essential concepts of NDS. However, 
there are few practical items we want to mention about programming 
with the NDS APIs. 


In order to program to the NDS APIs, you will always need to do two 
things at the beginning of your program: call NWInitUnicodeTables and 
then call NWDSCreateContext. Then, when your program is done 
executing or it encounters a fatal error condition, you will need to call 
NWDSFreeContext and NWFreeUnicodeTables. 


In the function call reference for the NetWare Client SDK for C always 
identifies which parameters of an API are input and output. If, for 
example, an output parameter is a WORD value, you would need to 
declare a WORD variable to receive that information. If the output 
parameter is a buffer, you would need to allocate memory for that buffer 
(by declaring a structure or using a call like malloc). In NDS, however, 


NetWare Directory Services Theory 155 





In NDS, however, many of 
the calls use special NDS 
buffers, and you need to 
create these buffers using 
the call NWDSAllocBuf. 


Stack Requirements 


many of the calls use special NDS buffers, and you need to create these 
buffers using the call NWDSAllocBuf. The buffers created by this call 
are 4096 bytes long and begin with a structure called Buf_T or 
NWDS_BUFFER which provides information about the current state of 
the buffer. 


A number of APIs are provided to put parameters into NDS buffers. These 
functions, which include APIs like NWDSPutAttrName and NWDSPut- 
Filter, are documented in the functional call reference of the Client SDK. 
APIs that take information out of NDS buffers, like NWDSGetAttrVal and 
NWDSGetObjectName, are also documented there. 


If you are using an NDS buffer to send information to the server, you 
will need to call NWDSInitBuf before passing the buffer to the API. Also 
remember to call NWDSFreeBuf when your program is finished execut- 
ing or encounters a fatal error condition. 


A common problem people encounter in programming to NDS is they 
do not allocate enough stack space. As a general rule of thumb add an 
additional 6KB of stack for NDS to whatever stack your program 
requires. 


Other Sources of Information 





If you want some additional high-level information about NDS, you can 
refer to chapter 4 of May 1993 version of the Novell NetWare 4.0 
Architecture manual which is shipped with the NetWare NLM SDK and 
the CD version of the SDK. Ifyou are installing NetWare 4.x for the first 
time, you will find some excellent information about planning NDS 
trees in the April 1993 issue of NetWare Application Notes. If you are 
interested in the specifics of programming to NDS, we suggest you read 
the first four chapters of the NetWare Programmer’s Guide for C. If you 
are interested in the object class definitions of the base objects provided 
with NDS objects or you are interested in extending NDS to include 
new objects, we suggest you refer to the Directory Services Schema 
Specification which is included in the NetWare NLM SDK or on the CD 
version of the SDK. 
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“This is a directory of Paris,” said he, “with the trades after the 
names of the people. I want you to take it home with you, and to 
mark off all the hardware sellers, with their addresses. It would 
be of the greatest use to me to have them.” 


—A. Conan Doyle, The Stock—Broker's Clerk 


Writing an application to scan the NetWare Directory is a little more 
complicated than scanning the bindery because the structure of the 
NetWare Directory is more complicated. In the Directory, objects exist 
in a hierarchical arrangement. This affects the way you scan the 
Directory as well as how you move around it. The assumptions we make 
for simplifying this application are found in Figure 11-1. 
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PROGRAM: Dz. EXE 


DESCRIPTION: Displays the attributes and values of objects 
in the NetWare Directory. 


SYNTAX: DS2 


REMARKS: DS2 begins at the [Root] of the directory or 
the current context of the workstation. After 
retrieving a list of all objects at that 
level, it queries the directory for a full 
list of the objects’ attributes and attribute 
values. 


The objects’ names, attributes, and attribute 
values are all output to a file named 
DSDUMP.OUT. 


SIMPLIFYING 
ASSUMPTIONS: 1. The directory context is set on the 
workstation. 


2.All NDS object types are dumped. 


3. If an attribute is specified, the 
application will only dump the information 
for that attribute. 


4.I1f an attribute is specified, the 
application does not verify if the object 
belongs to a class that has the attribute 
before attempting to query the Directory 
for the attribute. 


5. If an attribute is multi-valued, only the 
first value is output. 


Figure 11-1. Simplify- 
ing Assumptions for 
Scanning the NetWare 
Directory. 
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Setting up to Use the 
DLLs 


Scanning the Directory 





The Sample Source File DS.C . 





The application consists of the main function, the SetupToUseSDK 
function, and the DeinitSDK function. The SetupToUseSDK function 
initializes the DLLs used in the example code. The DeinitSDK function 
will deinitialize the DLLs with the appropriate calls. 


The two DLLs that the application uses are NWNET.DLL and the 
NWLOCALE.DLL. NWLOCALE.DLL contains all the function calls 
necessary to determine the locale in which the application is being 
executed. Using one of these function calls, we can get the country ID 
and code page value that need to be passed to NWInitUnicodeTables. 
The functions in NWNET.DLL that communicate with the Directory 
use the UNICODE tables to convert all strings to and from UNICODE 
and the local code page. 


The pseudo-code in Figure 11-2 demonstrates the steps you take in 
order to scan the Directory. Before using any of the NWDS_BUFFER 
(NDS buffers) types, you need to allocate them as shown in Figure 11-3. 
This allocation is based on the size specified in the call. A pointer to the 
buffer is returned, but must be freed using the NWDSFreeBuf call. 
These APIs assure the application of buffer sizes that are adequate for 
Directory communications, but leaves your code independent of any 
changes in this size between versions of the directory. 


After you have your buffers properly allocated, you need to create the 
context handle. The context will be initialized to your current context in the 
directory. This context can be changed using the CX.EXE utility provided 
with NetWare. The top of the directory tree is the [Root] context. The 
enhancement section at the end of the chapter will talk about what you 
need to do to change this application to walk the entire tree. 


Using your context handle, you are able to list all the objects that are 
below your context, or the subordinate objects to your context with 
NWDSList. Once your subordinate object buffer has been filled in, you 
can get the number of objects it contains. For each of the objects, you 
can get the object name, your effective rights to the object, and all the 
attributes and attribute values for the object. The iteration variable will 
be OxFFFFFFFF when you have retrieved all the subordinate objects. 
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allocate NDS buffers 
allocate memory for object and attribute information buffers 
create an NDS context 


LOOP while there are still some more subordinates 


call NWDSList 
call NWDSGetObjectCount 


LOOP for as many subordinate objects returned 


call NWDSGetObjectName 
call NWDSGetEffectiveRights 


LOOP do/while there are more attributes 


call NWDSRead for all the attributes 
call NWDSGetAtrCount 


LOOP for the number of attributes from this query 








call NWDSGetAttrrName 
call NWDSGetEffectiveRights for this attribute 
call NWDSComputeAtrValSize 


allocate a buffer for the attribute value 


call NWDSGetAtrVal 


Figure 11-2. Pseudo- 
code for Scanning the 
NetWare Directory. 


err = NWDSA]locBuf(DEFAULT_MESSAGE_LEN, 
&subordinates); 
if (err) 
goto CleanUp; 
err = NWDSAl]locBuf (DEFAULT_MESSAGE_LEN, 
&attrsBuf): 
if (err) 
goto CleanUp; 
err = NWDSA1]locBuf(DEFAULT_MESSAGE_LEN, 


&attrNamesBuf); 
if (err) 
goto CleanUp; 
Figure 11-3. 
Allocating NDS 
Buffers. 
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To get the attributes, you make a call to NWDSRead with the infoType 
variable set to DS_ATTRIBUTE_NAMES if you want only the attribute 
names or, if you want both the attribute names and values, set to 
DS_ATTRIBUTE_VALUES. Before making this call, you will also need 
to initialize the NDS buffer specifying the attribute names you want to 
limit this call to. You do this by calling NWDSInitBuf with a DS_READ 
flag. Then, using NWDSPutAttrName, fill the buffer with the attributes 
that you are interested in. If you want all the attributes, put “*” in the 
buffer. The iteration variable will be OXFFFFFFFF when you have 
retrieved all the attributes available. 


Each time you make a call to the NetWare Directory, you use an NDS 
buffer. This buffer is filled in. In order to access the information in this 
buffer, you must make calls to find out how many items are in the 
buffer, what their names are, and what their values are. These calls will 
unpack the buffer for you. The pseudo-code in Figure 11-2 indicates 
which calls are necessary to unpack the object buffer returned by 
NWDSList and the attribute buffer returned by NWDSRead. 


Enhancements to the Application 





If you want to walk the NetWare Directory tree from your application, 
you would just need to call NWDSSetContext to the context you wish to 
be in. The top of the directory tree is the [Root] context. To traverse 
the tree, you can set the context to container class objects. The call 
NWDSListContainableClasses will specify all effective classes that can 
be containers. The classes of the objects from NWDSList can be 
compared to these classes. Any of the objects that are container classes 
can be set as the context. 


If you want your application to search the tree for specific types of 


objects, you can use NWDSSearch to get objects instead of NWDSList 
and NWDSRead. 


A NetWare Directory Services Sample Application 161 





To create or add an object, you must initialize and build an NDS buffer 
that contains the full definition for an object. To initialize the buffer, you 
call NWDSInitBuf with the defined value for the action you want to take. 
Figure 11-4 lists the possible defines for this flag. Initializing the buffer 
isn’t necessary with every call, only the more generic calls like 
NWDSRead, NWDSModify, NWDSAdd, etc. as specified in the function 
call reference. To build this buffer, you make calls to put names and 
values in the buffer. To find out what attributes an object class needs, 
you make calls to get the object definition and the appropriate attribute 
definition. Using this information, you build the object in the NDS 
buffer. 


#tdefine DSV_RESOLVE_NAME 

define DSV_READ_ENTRY_INFO 

#tdefine DSV_READ 

#tdefine DSV_COMPARE 

#tdefine DSV_LIST 

4tdefine DSV_SEARCH 

#tdefine DSV_ADD_ENTRY 

define DSV_REMOVE_ENTRY 

#tdefine DSV_MODIFY_ENTRY 

#tdefine DSV_MODIFY_RDN 

#tdefine DSV_DEFINE_ATIR 

define DSV_READ_ATTR_DEF 

#tKdefine DSV_REMOVE_ATTR_DEF 

#tdefine DSV_DEFINE_CLASS 

#tdefine DSV_READ_CLASS_DEF 

#tdefine DSV_MODIFY_CLASS_DEF 

define DSV_REMOVE_CLASS_DEF 

#tdefine DSV_LIST_CONTAINABLE_CLASSES 

#tdefine DSV_GET_EFFECTIVE_RIGHTS 
Figure 11-4. Defini- define DSV_OPEN_STREAM 


ae a ath define DSV_SEARCH FILTER 


To change or modify an object, you call NWDSRead for the full object 
and all its attributes, then change the attributes or values by using 
NWDSPutAttr or NWDSPutAttrVal. 


Applications utilizing NetWare Directory Services are able to navigate 
the entire NetWare network. This makes management and application 
deployment on the network much easier. An application can create 
additional object classes that are necessary for it to function or to find 
its resources anywhere on the network. 
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“My friends lamented my connection with him, but I was to 
make the best of it.” 


—Autobtography of Benjamin Franklin 


NetWare Connection theory used to be relatively easy. You were either 
connected to a file server, or you weren't; and you were either attached 
or logged in. But with the introduction of NetWare Directory Services 
(NDS) in NetWare 4.x, things have gotten a bit more complicated. But 
this complexity does not arise so much from NDS itself, but rather from 
the almost unavoidable situation of having a mix of Bindery (2.x and 
3.x) servers and NDS (4.x) servers on the same network. But, with luck, 
we can sort it all out in this chapter. 
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Requester Initialization — 





One assumption that we’re making in this book is that you are writing 
network applications. That is, we’re assuming that whatever applica- 
tion you write using the Client SDK will be run after the requester has 
loaded. Nevertheless, we thought it might be useful to know what the 
requester does when it initializes and what initial state you can expecta 
workstation to be in when youre finally in a position to run your 
applications. 


The first thing the NetWare requester for OS/2 does is send out some 
Routing Information Protocol (RIP) packets and Service Advertising 
Protocol (SAP) packets to find out what servers are available on the 
network. Generally, the nearest or fastest file server on the network 
will respond, and you will get a connection to that server. This connec- 
tion has very few rights to do anything on the server except read 
routing tables and read some bindery attributes (like the address of the 
server). 


If you are in an environment where the only NetWare server may come 
and go—like on a network where you only bring the server up for 
testing purposes—you will probably want to work out a system to 
switch back and forth between a CONFIG.SYS file with the requester 
files installed and one that doesn’t. Otherwise, if the file server is not 
available, you will have to wait for the SAP and RIP packets to time-out 
and for the requester to give you error messages. 


Getting back to connections, though, the file server considers this 
initial connection to be “NOT-LOGGED-IN.” In NetWare 2.x and 3.x, 
these NOT-LOGGED-IN connections counted against the user license 
of the file server. For example, if you had a five-user version of 3.11 and 
there were five NOT-LOGGED-IN connections, another workstation 
would not be able to attach at all, let alone log in. This is one of the 
limitations that was removed by NetWare 4.x. NDS servers can support 
virtually unlimited service connections or NOT-LOGGED-IN connec- 
tions. In fact, in the course of authenticating a user to another server 
the Directory may create a number of connections to additional file 
servers. (The requester caches a certain number of these additional 
connections on a Least Recently Used or LRU basis.) 
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If you are on a network 
with no 4.x servers, you 
will want to include the 
statement “DIRECTORY 
SERVICES OFF” under 
the “NETWARE 
REQUESTER” heading in 
your NET.CFG file. 





The next thing the requester does is look for an NDS server. Unless 
you have specified otherwise in your NET.CFG, the requester will try to 
establish it’s initial drive to an NDS server. For this reason, if you are on 
a network with no 4.x servers, you will want to include the statement 
“DIRECTORY SERVICES OFF” under the “NETWARE REQUESTER” 
heading in your NET.CFG file. 


If, in addition to “Preferred Tree,” you have a “Preferred Server” state- 
ment in NET.CFG, the requester will also try to make a connection to 
the preferred server. So depending on your network and your 
NET.CFG settings, the requester may initially have several connections 
to servers which generally fall into the following four categories: 


the first server to respond to the Get Nearest Server SAP packet 
the first NDS server found that is in the PREFERRED TREE 
the server that is specified by PREFERRED SERVER 


any NDS servers that were found before the requester found the NDS 
server in the preferred tree 


It is also very possible that after initialization you will only have one 
connection to a server—where the first server to respond is an NDS 
server in the preferred tree you specified. 


After establishing connections, the requester does some additional 
work to establish communication with the server. This includes things 
like negotiating an optimal packet size, setting up Packet Burst (PB), 
setting up Large Internet Packet transmissions, etc. This activity 
largely depends on what entries you have in your NET.CFG. 


The last thing the requester does is map drive L: to the SYS:LOGIN 
subdirectory of either the NDS server it connected to (if one was found 
in the preferred tree or if no other specification was given in NET.CFG) 
or to the bindery server it connected to (as preferred server or, if 
nothing else was specified, the server which responded first). If the 
server is configured properly to support OS/2, there should be OS/2 
utilities—specifically MAP and LOGIN—available in the SYS: LOGIN/ 
OS2 subdirectory to allow you to log in and map drives. In the event 
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that OS/2 utilities are not available, the requester install program also 
copied these utilities to your local drive. Unless you specified a differ- 
ent subdirectory name, these utilities should be available in the 
\NETWARE subdirectory. 





Connection Types: NDS and Bindery 


Before NetWare Directory Services (NDS), connections were made on 
a server by server basis. That is, you had to connect to a server to get 
information about it and about its users and its other resources. Each 
server kept this information in a database called the bindery, and the 
information necessary for you to log in as a specific user was kept there. 
In NDS, however, a layer of abstraction called the Directory was put in 
place above individual servers. With NDS, instead of having a bunch of 
individual servers on a network, you could group the servers into a tree 
To take advantage of the and put all the information about users and available resources at the 


capabilities of NetWare tree level. 


Directory services, though, yo. example, let’s say your network has been configured under the 


your workstation must usé industry standard convention of naming servers after ships in Herman 
the NetWare DOS’ Melville’s Moby Dick. Depending on the task at hand, you may need to 
Requester (or VLM) or connect to servers PEQUOD, ROSE-BUD, and SAMUEL_ENDERBY. 
version 2.01 or later of the With 3.1x servers, this would require you to connect to each server, log 
in (or attach) with a specific user name and password, and then map 
drives to specific subdirectories—a total of nine separate operations on 
your part. However, if these servers were 4.x servers and had been put 
in a tree named MOBY_DICK, you could attach to any one of the 
servers, log into the MOBY_DICK tree with a specific user name and 
password, and then map drives to specific subdirectories on each 
server—a total of five separate operations on your part. NDS would 
take care of getting the connections to the other servers, and 
authenticating your user name on those servers, (i.e. logging you in). 


NetWare requester 
for OS/2. 


An NDS connection, then, not only provides you with all the functional- 
ity of a bindery connection, it also allows your workstation to communti- 
cate with the Directory. To take advantage of the capabilities of 
NetWare Directory services, though, your workstation must use the 
NetWare DOS Requester (or VLM) or version 2.01 or later of the 
NetWare requester for OS/2. 
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Upgrading Connection Types — 





Keep in mind that connection types are a client-side consideration only. 
It arose from the need to add the new Directory capabilities to the client 
requesters and, at the same time, keep the requesters compatible with 
2.x and 3.x servers. NetWare 4.x servers don’t keep track of NDS and 
bindery connections in the same sense as workstations do. 


Another way of looking at connections is to determine if they are NDS 
capable or not NDS capable. For example, when you connect to a 
server using the NWAttachToFileServer API, the requester doesn’t 
know if the connection is NDS capable or not. However, by virtue of the 
fact that the client has a connection, the application can then use the 
NWIsDSServer call to find out if the server supports NDS. However, 
even if the server is an NDS server, the connection is not necessarily 
upgradeable to an NDS connection. If the connection is to an NDS 
server in a tree other than the current tree, the connection—while NDS 
capable—must be bindery. But if the connection is in the same tree or 
it is the first NDS connection, then you can call NWDSLogin to upgrade 
the connection type to NDS. 


The next chapter has pseudo-code and sample source code that de- 
scribes the tests and conditions you can use to determine if a connec- 
tion is NDS capable, upgradeable, or fully authenticated through NDS. 


Connection States 





Once you've worked out the issues of what type of connection you are 
dealing with, you will then need to deal with the issues of what “state” 
the connection isin. Bindery connections have two states: attached and 
logged-in. Attached means you have a connection to the server, but you 
have only limited access to that server’s routing tables and to whatever 
files may be in SYS:LOGIN. Logged-in means you have provided the 
server with a valid user-name and password and that you have access to 
the file system and other resources like print services. In the para- 
graphs above, we used the term “connected” in the sense of “attached.” 
All the connections made during the requester’s initialization are “at- 
tachments” or “NOT-LOGGED-IN” connections. 
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NDS connections have three states: attached, logged-in, and authenti- 
cated. We have chosen these terms because they correspond to the 
names of the APIs you use to achieve that state. (In different Novell 
publications you may see some inconsistent use of these terms.) 


Attached means you have a connection to the server. It is NOT- 
LOGGED-IN and, again, has limited rights to information contained in 
the server. Logged-in means you have provided a valid user-name and 
password to the Directory and now have rights to get information from 
the Directory. Authenticated means that you have access to the file 
system of a particular server as well as other resources like print 
Services. 


Figure 12-1 illustrates the relationships between these states. 


| Bindery Connection = Connection NetWare Directory Services Connection 


Access Access 
| Povileges | | Prvileges 


‘ive | - Routing Routing Tables N uwattachToFileServer T attached - Routing foarte | sN  swWAitachToFileserver 
- SYS:LOGIN - SYS:LOGIN 

(With NetWare (Does not 

2.x and NetWare count against 

3.x, counts license) 

against license) 


Logged-In - File System NWLoginToFileServer Logged-In - Directory NWDSLogin 

- Server 
(Counts against resources (requires user name (Does not (requires user context 
license) and password) count against and password) 


Authenticated | - File System NWDSAuthenticate 
(Counts against] - Server 
license) resources 





Figure 12-1. 
Differences Between 
Bindery and NDS 
Connection States 
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You map drives to 
subdirectories on that 
server using the 
NWSetDriveBase call. 





Mapping Drives 


Mapping a drive is the easiest part of all this connection business. Once 
your application has logged-in to a server or been authenticated through 
the Directory to a server, you map drives to subdirectories on that 
server using the NWSetDriveBase call. Conversely, you can “unmap” 
drives by calling NWDeleteDriveBase. 


Remember, though, that the user ID you used to log in (or authenti- 
cate) to the server with must have sufficient rights to the subdirectory 
you're trying to map to. 


Logging-Out 


Logging out has essentially the same considerations as getting an NDS 
connection or a Bindery connection. That is, you can log out of a single 
file server, or you can log out of a directory tree. A single server log out, 
or “bindery” log out, simply changes the state of a bindery connection 
from logged-in to attached. You will, however, still be connected to that 
file server until you call NWDetachFromFileServer to detach from it. 


An NDS log out changes the state of all NDS connections—every 
connection your workstation has in the tree—from logged-in or authen- 
ticated to attached. After logging out, you may still have connections to 
all your NDS file servers, and you will need to call NWFree- 
ConnectionSlot to get rid of the cached NDS connections on the LRU. 


The only real consideration involved in logging out comes up when you 
are trying to log out of all file servers, and you have to decide which 
connection to log out of last. You generally make this decision by 
evaluating certain connection designations. 


Connection Designations 





There are four distinct connection designations: 
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e Monitored Connection 
e Default Connection 
e Primary Connection 


e Preferred Connection (do note confuse this with the Preferred Connec- 
tion ID which was used in previous APIs but no longer exists) 


Figure 12-2 describes how these connections are defined in the context 
of the Client SDK. These designations can be determined by making 
the API calls identified in Figure 12-2. 


Connection Significance 
Designation 


Monitored Connection This designation only applies to NDS capable 
connections. This connection contains a writable NDS 
replica of the object you logged in with. Logging out 
of server to which the monitored connection is at- 
tached requires you to log out of the Directory. 


Use the NWDSGetMonitoredConnec-tion API to 
determine this connection. 


Default Connection This is the connection that maps fo the 


(Continued) “current directory.” That is, if the current drive is 
mapped to a subdirectory on a NetWare server, the 
connection that was used to map that drive is the 
default connection. 


If the current drive is not a NetWare drive, the default 
connection is the same as the primary connection. 


lf there is no primary connection, the default 
connection is the first connection in the workstation’s 


Figure 12-2. Connec- connection table. 
tion Designations in 
the Client SDK 
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Figure 12-2. 
Connection 
Designations in the 
Client SDK. 
(Continued) 





Connection Significance 
Designation 


Default Connection Use the NWGetDefaultConnectionID 
(Continued) API to determine this connection. 


Primary Connection This is the connection from which the login script was 
read. 


Use the NWGetPrimaryConnection!D API to determine 
this connection or make the NWGetConnectionStatus 
API and test connectFlags with CONNECTION_ PRI- 
MARY. 


Preferred Connection This is the connection to the server specified in the 
NET.CFG as PREFERRED TREE NAME or, if it is not 
specified, the server specified in PREFERRED SERVER 
NAME. 


Use the NWGetPreferredConnName API to determine 
this connection. 


However, with respect to logging out of all servers, you will generally 
want to log out of the Monitored connection last. If a monitored 
connection does not exist, you will want to log out of the default 
connection last. And if a default connection does not exist, log out of the 
primary connection last. 
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Error should, tf possible, be avoided. 


—Aristotle, The Poetics 


We have written two applications for this chapter, VNRMAP and 
VNRLGOUT. As its name suggests, you can use VNRMAP to map 
drives to a specified server by making either NDS or Bindery connec- 
tions to that server. VNRLGOUT is used to log out of a single server or 
all connected servers. The functionality and simplifying assumptions 
for these two applications are described in Figures 13-1 and 13-2 
respectively. 
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Figure 13-1. 
Description and 


Simplifying 


Assumptions for 
VNRMAP. 


Figure 13-2. 
Description and 
Simplifying 
Assumptions for 
VNRLGOUT.EXE. 


PROGRAM: 


DESCRIPTION: 


SYNTAX: 


REMARKS: 


SIMPLIFYING 
ASSUMPTIONS 


PROGRAM: 


DESCRIPTION: 


SYNTAX: 


REMARKS: 


VNRMAP.EXE 


Makes a connection and maps a drive to the 
Specified server and subdirectory. 


VNRMAP driveLetter server/volume:path 


VNRMAP makes the highest level connection 
possible to the server specified. That is, 
if the server is an NDS server, VNRMAP 
will try and make an NDS connection to it 
first, and then, if necessary, make a 
bindery connection. 


As with all OS/2 drive mappings, the drive 
will be mapped root at the subdirectory 
Specified. 


« If you want to connect to a server 
outside of the current (and 
authenticated NDS tree), we do a bindery 
connection. We do not logout out of the 
current NDS tree and re-login in the new 
NDS tree. 


« We do not process login scripts. 


VNRLGOUT.EXE 


Logs you out of all servers or the server 
Specified. 


VNRLGOUT [LserverName ] 


VNRLGOUT with no parameters will logout of 
every server to which you are connected as 
well as log you out of any NDS tree you 
are authenticated to. 
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Figure 13-2. 
Description and 
Simplifying 
Assumptions for 
VNRLGOUT.EXE. 
(Continued) 


VNRAttachToFileServer 


If you specify a serverName with VNRLGOUT, only that 
server will be logged out. If the server specified 
contains the NDS monitored connection, you will also 
be logged out the NDS tree, and any servers to which 
you were authenticated in that tree. 


SIMPLIFYING 

ASSUMPTIONS: e We do not display the server name or 
any date and time information like 
the NetWare LOGOUT utility does. 


The application VNRMAP essentially makes use of two functions we 
have written: 





VNRAttachToFileServer 


VNRMapDrive 


The difficulty in writing a function like this arises when you try to 
support both NetWare Directory Services (NDS) type connections and 
bindery type connections. If you have the luxury of dealing with a 
completely bindery or a completely NDS world, life is simple: bindery 
connections are created using NWLoginToFileServer and NDS connec- 
tions are made by calling NWDSLogin. But if you have a network of 
mixed bindery and NDS servers, the trick is all in determining which 
call to make. 


The clearest way we could think of to illustrate the tests and conditions 
that need to be applied in order to make the right kind of connection 
was to use a high-level pseudo-code. Consequently, Figure 13-3 pro- 
vides a pseudo-code outline of VNRAttachToFileServer. 


A Connection Services Application 175 


set flag DSCapableConn=FALSE /* unless determined otherwise, 
connections are bindery */ 
set needLogin = TRUE /* unless determined otherwise, our 
connections need to be logged in */ 


IF the workstation is NOT connected to the specified server 


get a connection to the specified server by calling 
NWAttachToFileServer 


/* at this point the workstation has a connection to the specified 
server */ 


call NWIsDSServer 
IF the specified server is an NDS server 
set DSCapableConn=T RUE 
put the name of the tree in which the specified server resides 
jnto a string name TreeName 
/* otherwise specified server is a Bindery server and DSCapableConn 
16 ST111 false */ 
IF DSCapableConn=FALSE 
set kindOfConnection=CONNBIND 
BLSE 
/* connection is potentially NDS */ 
call NWIsDSAuthenticated 
IF the workstation is logged in to an NDS tree 
call NWGetPreferredConnName 


IF the authenticated tree name does NOT match TreeName 
(the tree the specified server is in) 


keegan /* All NDS connections must be in the same tree. Even if 
code for Function ; ; 
VNRAttachToFileServer. the connection is NDS capable, you must make the 


connection bindery because the server is not in the 
Same tree. */ 
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set kindOfConnection=CONNBIND 
ELSE 

/* tree names match */ 

kindOfConnection=CONNNDS 


Set needLogin=FALSE /* NWIsDSAuthenticated indicated 
we’re already logged into tree*/ 


ELSE 
/* no NDS connections so this connection can be NDS */ 


set kindOfConnection=CONNNDS 


call NWGetConnectionStatus to get connectFlags 
IF kindOfConnection = CONNBIND 
/* connection should be bindery */ 
IF connectFlags indicates CONNECTION _LOGGED_IN 
/* no work needed, connection is already logged in */ 
ELSE 
/* need to do a bindery login */ 


call NWLoginToFileServer 


ELSE 
/* connection is a DS connection */ 


IF connectFlags indicates CONNECTION _AUTHENTICATED 


Figure 13-3.Pseudo- /* no work need, connection is already authenticated */ 
code for Function 
VNRAttachToFileServer. FLSE 
(Continued) 
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/* connection is not authenticated yet */ 


call NWInitUnicodeTables 
call NWSetPreferredDSTree using TreeName (the tree the 
Specified server is in) 
call NWGetPreferredDSServer 
get a context handle by calling NWDSCreateContext 
IF needLogin = TRUE 
Cannonicalize specified user name 
call NWDSLogin 
IF NWDSLogin fails 


append specified server context to specified user name 


call NWDSLogin with user name at server context 


call NWDSAuthenticate 
/* workstation is connected and logged in */ 


free context and unicode tables 


Figure 13-3. Pseudo- 
code for Function 
VNRAttachToFileServer. 
(Continued) 


The pseudo-code starts by testing whether the workstation has a con- 
nection to the file server specified. You can determine this by calling 
NWGetConnectionList which returns an array of all your workstation’s 
connection handles. You can then use any of several calls that will 
return the file server name from the connection handle and see if one of 
the connected file server names matches the specified file server name. 
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VNRMapDrive 


In our function we used NWDSGetConnectionInfo because in earlier 
versions of the function we were interested in the information contained 
in the variable connType: i.e. is the connection licensed or authenti- 
cated. The current function does not use connType, but we left it in here 
because, even though NWGetConnectionStatus will provide the server 
name, we wanted to show an example of how to make another call that 
returns connection information. 


After you have determined whether you have a connection to the 
server, there is only one other thing in the pseudo-code outline that 
merits additional comment—the two calls to NWDSLogin. The first call 
to NWDSLogin may fail if the user name specified is not in the root 
context of the tree. Consequently, we try a second NWDSLogin at the 
same context as the specified server just in case the user name exists at 
that context. 


A final thing to keep in mind, though, is NDS authentication calls can be 
very slow. Depending on how many servers make up your tree, you 
may need to wait upwards of 15 seconds for VNRAttachToFileServer to 
complete. (And yes, while you’re waiting for NWDSAuthenticate API to 
complete all your other NetWare applications or threads running in 
OS/2 will be blocked.) 


Once you have a logged-in connection, or an authenticated connection, 
mapping a drive takes one API call—NWSetDriveBase. Of course there 
is a bit of set up work you need to do to make this call, and we have 
listed the steps that our function VNRMapDrive uses: 


1) Convert drive letter to a drive number (i.e., A=1, B=2, C=3, etc.). 
2) Call NWGetDriveStatus to see if the drive number is in use. 


3) Call NWGetConnectionHandle to get a connection handle to the 
specified server. 


4) Add the volume name to the path you want to map the drive to. Separate 
the two by a colon. For example, the path string you pass to 
NWSetDriveBase should look something like this: 
SYS:HARPOONEERS/MAIL. 


o) Call NWSetDriveBase to map the drive. 
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Bindery Login Scripts 


On a bindery server, the 
login script read by the 
OS/2 LOGIN program 1s a 
file named LOGIN. OS2. 


Login Scripts 





If you have used the NetWare LOGIN utility, you are probably familiar 
with login scripts. A login script is like a NetWare batch file that the 
LOGIN utility executes after it logs you into a file server. This script 
usually tells the LOGIN utility to make attachments to other servers, 
map drives, and capture printer ports. If you wanted to—and if you have 
no other meaningful activities to occupy your time—you could write a 
parser that would allow your program to interpret and/or execute login 
scripts. However, be aware that there are two kinds of login scripts: 
bindery login scripts and NDS login scripts. 


Bindery login scripts are saved in files on volume SYS in subdirectories 
below the MAIL directory which are named after the user’s bindery ID. 
On a bindery server, the login script read by the OS/2 LOGIN program 
is a file named LOGIN.OS2, and the file read by the DOS login program 
is LOGIN. For example, if your program were to log in a user 
QUEEQUEG, you could, after calling NWLoginToFileServer, perform 
the following steps to read the bindery login script: 


1) Call NWGetObjectID to the get the objectID for user Queequeg. 


2) Let’s say that the bindery object ID is 10000A2. You would want to 


convert this number to a string (a bindery ID string, if you will). 


3) Create a path string by appending the bindery ID string to SYS:MAIL to 


get a path string that looks something like this: SYS:MAIT\10000A2. 


4) At this point you can either map a drive to volume SYS using this path 


string (and then open the file LOGIN.OS2 on that drive) or you can call 
NWAllocTemporaryDirHandle to get a directory handle to the 
SYS:MAIL\LO000A2 subdirectory. 


5) Open the file LOGIN.OS2. 


6) Parse away. 


If you want to parse the system login script, it is contained in the file 
NETSLOG.DAT in the PUBLIC subdirectory. 
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NDS Login Scripts 


In NDS, the login script ts 
a stream associated with 
the user object. You can 

get a file handle to the 
login script stream by 
calling NWDSOpenStream 
using the user name. 


Logging out of a Single 
Server 


In NDS, the login script is a stream associated with the user object. You 
can get a file handle to the login script stream by calling 
NWDSOpenStream using the user name. For example, in the 
VNRAttachToFileServer function, you could get access to the user’s 
login script after you call NWDSAuthenticate. One way to do this is to 
make the call to NWDSOpenStream in the following manner: 


NWDSOpenStream( contextHandle, 
workspaceDN, 
“Login SCFIpPt™. 
DS_READ_STREAM, 
&fileHandle); 


Remember, that in order to log in we needed to canonicalize the user 
name which we then put in string named workspaceDN. If you want to 
access the system login script you would strip the common name off 
workspaceDN. For example, passing .CN=STARBUCK.O= 
MOBY_DICK as the object name in NWDSOpenStream would return a 
file handle to the login script for user STARBUCK. Passing 
.O=MOBY_DICK as the object name in NWDSOpenStream would re- 
turn a file handle to the system login script. 


a 





Logging out of a server is avery straightforward task. However, as with 
everything in the NetWare paradigm, there are a number of things to 
consider before doing this. 


To log out of a server, you simply call NWLogoutFromFileServer. In 
OS/2, however, you will first want to make sure that you release any 
printer ports that have been captured. We have written a function called 
releasePorts that will cycle through all of the available ports and, if 
necessary, call NWEndCapture for each port. (Also, note that the 
documentation is incorrect when it names the first field of the 
NWCAPTURE_FLAGSSRO as conn—it should be connID.) 
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Logging Out of All 
Servers 


Remember that even though you have logged out of a file server, your 
workstation will still maintain a connection to it. To get rid of a 
connection on a bindery server call NWDetachFromFileServer. To get 
rid of a cached NDS connection on an NDS server, you would call 
NWFreeConnectionSlot. In our logout application we call both to make 
sure that the connection goes away. But depending on your application 
you may want to keep the connections around, so you could forgo these 
two calls. 


In addition to logging out of a server, you may, if you are authenticated 
to a NDS tree, want to logout of the NDS directory. But more on this in 
a moment. 


The only trick to writing a function that logs out of all the file servers to 
which your workstation is attached—in the connection sense, not the 
emotional sense—is deciding which server to logout of last. We suggest 
you observe the following priorities in deciding which server will be the 
last one you log out of: 


1) The server which has your monitored DS connection 


2) The server which has your default connection 


3) The server which has your primary connection 


Logging out of the tree will 
also log you out of any 
servers that you connected 


to with NDS connections. 


The monitored connection is only available if you are using NDS, and 
you call NWDSGetMonitoredConnection to find out which server has 
this connection. The server which contains the monitored connections 
also contains NDS schema information critical to your workstation’s 
use of the directory. Consequently, you must call NWDSLogout to log 
out of the tree—and as a result, out of the server. Logging out of the tree 
will also log you out of any servers that you connected to with NDS 
connections. But remember it does not necessarily free the connec- 
tions’ slots. 


And again we have provided a function called logoutDSTree that will log 
your workstation out of its current NDS tree. 
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Logout of the Last 
Server 


In almost every case where you do not have a monitored connection, 
you will want to logout of the default connection last. You determine 
this connection by calling NWGetDefaultConnectionID. However, in the 
rare event that there is not a default connection, call 
NWGetPrimaryConnectionID to determine which server contains the 
primary connection. 


In OS/2, the reason you need to concern yourself with the last connec- 
tion is that when you log out of your last server, you should call 
NWSetInitDrive to put your OS/2 workstation in the same state as when 
the requester first initialized. Whatever connection ID you pass to this 
call will be the server that the OS/2 requester maps its L: drive to. 
Again, this connection provides little more than access to a few NetWare 
utilities on that server. To get real file system access, you will need to 
log in to a server. 
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Security permeates every 
aspect of NetWare. 





I consulted several things in my situation, which I found would 
be proper for me. First, health and fresh water, I just now 
mentioned. Secondly, shelter from the heat of the sun. Thirdly 
security from ravenous creatures, whether men or beasts. 


—Daniel Defoe, Robinson Crusoe 





NetWare Security 


Security permeates every aspect of NetWare. From the contents of 
packets on the wire, to the Application Programming Interfaces (APIs) 
the NetWare client software presents to applications, NetWare’s 
designers have designed NetWare to be secure against a number of 
security threats. NetWare does not have a group of security APIs, but 
there are many aspects of NetWare security that developers need to be 
aware of. This chapter briefly introduces several of NetWare’s security 
features. We discuss many of these features in greater depth in other 
chapters. 


185 





NetWare 4 has APIs for auditing network usage. This chapter discusses 
NetWare 4 auditing APIs in some detail. 


Novell’s Systems Research Department has published two reports on 
NetWare security and auditing. These reports are written for network 
designers, administrators, electronic data processing (EDP) auditors, 
and consultants to each of these groups, but developers will also benefit 
from the discussion of NetWare’s security features. For NetWare 3, 
refer to “NetWare Security: Configuring and Auditing a Trusted Envi- 
ronment.” For NetWare 4, refer to the April 1994 issue of Novell 
Application Notes, a special edition entitled “Building and Auditing a 
Trusted Environment with NetWare 4.” 


NetWare Security Certification 





The U.S. Government’s National Computer Security Center (NCSC) 
and the European ITSEC organization evaluate and certify computer 
systems for compliance with security standards they have established. 
Each organization defines several levels of security, from minimal secu- 
rity to verified design. Manufacturers submit their products to these 
organizations to be evaluated for a specified security level. At this 
writing, NetWare 4 is being evaluated for C2 level certification by the 
NCSC, and E2 certification by the ITSEC. 


NCP Packet Signature 


NCP (NetWare Core Protocol) Packet signature is a security feature of 
NCP Packet Signature the NetWare DOS Requester (VLM) and NetWare server versions after 
3.11. When NCP packet signature is enabled, the server and worksta- 
tion “sign” each packet with a unique signature that includes a 
checksum for part of the packet. 


prevents users from 
“forging” a packet and 
assuming another client’s 
identity. NCP Packet Signature prevents users from “forging” a packet and 
assuming another client’s identity. For example, a user could identify 
the connection number of another user logged in as SUPERVISOR or 
ADMIN, then send a packet with the appropriate network address and 
sequence number to convince the server that the packet came from the 
SUPERVISOR’s workstation. The server would then allow the intruder 

to have SUPERVISOR access to the file server. 
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Figure 14-1. Bindery 
Security Levels. 





If you are an application developer, you typically would not be con- 
cerned with communication at the packet level, but systems program- 
mers frequently deal with the contents of packets. 


Bindery Security 


NetWare limits access to the bindery, to prevent unauthorized users 
from changing other users’ passwords, login scripts, etc. As we dis- 
cussed in the “Bindery Services Theory” chapter, the bindery contains 
objects, like user, file server, and print server objects. Bindery objects 
can have properties that contain data associated with the object—the 
user object’s password, for example. Bindery objects and properties 
have a security level that determines who has read or write access to 
them. There are five security levels, and each object or property has 
separate security level values for reading or writing. Figure 14-1 ex- 
plains the five security levels. 


Anyone Access allowed to any client, even if they are not logged in 
to the file server. 

Logged Access allowed only to clients who are logged in to the file 
server. 
Access allowed only to clients who are logged in as the 
object, or are security equivalent to the object. 

Supervisor Access allowed only to clients logged in as SUPERVISOR or 
equivalent. 

Bindery Access allowed only to the operating system. 


The “Bindery Services Theory” chapter has more information about 
object and property rights. 
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_ Directory Security 





NetWare Directory Services (NDS) security is more flexible than bind- 
ery security, and therefore more complex. Some of the differences 
between bindery and NDS security are: 


Under bindery security, read and write access are granted to classes of 
objects, rather than individual objects. For example, if read access to an 
object is set to Logged, any object logged in to the file server can read 
the object and its properties. Under NDS security, each object can be 
granted different access rights to an object. 


e With the bindery, when an object has rights to another object, it has the 


same rights to the object’s properties. Under NDS, an object can be 
granted different rights to another object and each of its properties. 


e The bindery is a flat database; granting rights to one object does not 


Object Rights 


Figure 14-2. NetWare 
Directory Services 
Object Rights. 


affect any other part of the database. The Directory is hierarchical; 
objects at lower levels of the Directory tree inherit the rights granted to 
an object higher in the tree. 


Each object (user, volume, organizational unit) in the NetWare Direc- 
tory can be assigned rights to any other object. An object that has been 
granted rights to another object is called a trustee. There are five NDS 
object rights, which are summarized in Figure 14-2. 


‘ioe ifon 
The right to see the object in the Directory. 


Create The right to create new objects below a container object in the Directory 
tree. Applies only to container objects. 

Delete The right to delete objects from the Directory. Only leaf objects and 
empty container objects can be deleted. 


The right to change the name of an object. Applies only to leaf objects. 


Supervisor All rights to the object and its properties. 
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Property Rights As in the bindery, NDS objects can have properties. NDS properties 
can have more than one value. Any object in the Directory can be 
granted one or more rights to a property. Property rights are summa- 
rized in Figure 14-3. 


a 


Compare The right to compare a value to the value of the property. 
This right does not allow you to read the value, but only to use 
NWDSCompare to compare it to a specitied value. 


Read The right to read the values of a property. Also allows you to 
use NWDSCompare to compare the property's value to a 
specified value, even if the Compare right has not been 
explicitly granted. 


Write The right to add, remove, or change any values of the 
property. 


Add or 

Delete Self The right of an object to add or remove itself as a value of the 
property. The object granted this right cannot change any 
other values of the property. This right is useful for creating 
group lists; users could add or remove themselves from the 
list, but could not add or remove any other user. 


Figure 14-3. NetWare | Supervisor All rights to the property. 
Directory Services 


Property Rights. 
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Access Control Lists 


Rights to an object and its 
properties are stored in the 
object’s Access Control List 

(ACL) property. 


Inherited Rights 





As an example of how NDS uses object and property rights, when a new 
user object is created, the object is given the Browse right to itself, so 
that it can find itself in the Directory tree. The object is also granted the 
Read right to all its properties, and the Write right to its Login Script 
and Print Job Configuration properties. However, it would not be a good 
idea to grant a user object Write rights to its Account Balance property, 
for example. 


Rights to an object and its properties are stored in the object’s Access 
Control List (ACL) property. An ACLis a list of trustees of an object and 
its properties, and what those rights are. Each ACL value can specify 
rights for: 


e A specific property, like the Email Address property of a User object. 
e All properties of the object. 


e The object itself. 


Because the ACL is itself the property of an object, if the object is made 
a trustee of itself, and the object has the Write right to the ACL, the 
trustee can then modify any rights of the object or its properties. For 
example, if a user object has the Write right to its ACL, the user could 
change his or her own Login Allowed Time Map property to change the 
hours he or she is allowed to log in. 


Because of the way rights are inherited down the Directory tree (as we 
discuss next), it is not necessary to explicitly grant all rights to all 
objects. 


NetWare Directory rights flow from the root at the top of the tree, 
downward through the branches, to the leaves at the bottom of the tree. 
(From this we see that programmers need to get out more often.) 


When you make an object the trustee of a container object, objects 
below the container inherit the rights granted to the trustee. Figure 
14-4 illustrates a number of principles of rights inheritance. 
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Figure 14-4. NetWare 
Directory Services 
Inherited Rights. 


Root 


: Object: SUPERVISOR 
O=DESERT_ISLE_INC Obj. Rights: [ S ] 


OU=SUPERVISOR OU=ENG Object: RCRUSOE 
Obj. Rights: [ BC ] 

IRF[ ] IRF[ B ] 

OU=DESIGN OU=FAB 


USER=RCRUSOE 


RCRUSOE inherits [ S ] 
SUPERVISOR inherits [ ] 


mf TT 





RCRUSOE inherits [ B ] 
SUPERVISOR inherits [ S ] 





If a trustee is granted rights at two levels of the tree, the rights granted 
at the lower level flow down from that level. Trustee rights to part of the 
Directory tree can be revoked with an Inherited Rights Filter (IRF). You 
can use an IRF to revoke the rights granted to all trustees at higher 
levels of the tree. You can then grant rights to trustees in the part of the 
tree you are managing. 


The Supervisor right creates a unique situation with inherited rights. 
As shown in the figures above, NDS has both Supervisor object and 
property rights. If you use an IRF to revoke the Supervisor property 
right, trustees’ rights to properties will not flow down the tree below the 
IRF. The exception is with trustees that have been granted the Supervi- 
sor object right. The Supervisor object right implies that the trustee 
also has rights to the object’s properties. Filtering out the Supervisor 
property right does not block the Supervisor object right. 
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An IRF that filters the Supervisor object right prevents Supervisor 
access to the part of the tree below the IRF. Therefore, before filtering 
out the Supervisor object right, you should grant the Supervisor right to 
one or more objects for that part of the tree. If you create the IRF first, 
you will not have sufficient rights to grant Supervisor access to that part 
of the tree later. Once you have created an IRF that filters the Supervi- 
sor object right, you must also be careful not to delete all objects that 
have Supervisor access to the part of the directory tree below the IRF. 


Login Security and Account Restrictions 





Login security in NetWare is implemented in the Bindery or Directory, 
and is administrated by the SUPERVISOR or Admin user. To impose 
login security, the administrator creates user objects and sets login 
restrictions. The administrator can also set a password when the user 
object is created. Login restrictions that are available in NetWare are: 


e User account requires a password 
e Minimum password length 


e User must change passwords periodically (and how long before a 
password expires) 


e If, when changing passwords, the user must choose a password he or 
she has not used before 


e The number of logins the user is allowed after a password has expired 
(“grace” logins) 


e Hours of the day and days of the week the user is allowed to log in 
e Network addresses of workstations the user can log in from 


Account restrictions are properties of each user’s bindery object (in 
NetWare 2 or 3) or of the user’s NDS object (in NetWare 4). For more 
details, see the earlier chapters in this book on Bindery and NetWare 
Directory Services. Another good source of information for information 
on properties of user objects is the NetWare Directory Services Schema 
Specification, which is included with several software development kits 
(SDKs) from Novell. 
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When intruder detection 
is enabled, NetWare will 
lock out a user account 
after a number of 
unsuccessful login 
attempts during a 
specified period of time. 


Aside from the login restriction features, NetWare’s accounting feature 
allows the administrator to limit the amount of network resources 
(login time, file server requests, disk requests) the user is allowed. See 
the chapter in this book entitled “Accounting Services Theory” for more 
information. 


Intruder Detection 





Intruder detection works with login security features to secure NetWare 
against intruders. When intruder detection is enabled, NetWare will 
lock out a user account after a number of unsuccessful login attempts 
during a specified period of time. When setting up intruder detection, 
the administrator specifies: 


How many times a user can attempt to log in unsuccessfully before 
NetWare locks the user’s account 


How long the file server keeps track of unsuccessful login attempts 
How long the account will remain locked after an intruder is detected 
As with account restrictions, intruder detection is implemented as 


properties of user and server objects in the bindery, and properties of 
organization, organizational unit, and user objects in the Directory. 


File System Security — 





File system security in NetWare can be somewhat complex, especially 
when you are trying to write code that is compatible with multiple 
versions of NetWare. Rights to files and directories are primarily 
controlled by granting trustee rights to a file or directory. Figure 14-5 
describes trustee rights for NetWare files and directories. 


In NetWare 2, you can only grant trustee rights for directories. If you 


grant a user Read rights to a directory, they can read all files in the 
directory. Also, NetWare 2 does not have the Supervisor right. 
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Figure 14-5. NetWare 
Trustee Rights for 
Files and Directories. 


Supervisor 


When Granted 
for a Directory 


Trustee can open and read 
files in the directory. 


Trustee can open and write 
to files in the directory. 


Trustee can create files 
or subdirectories in the 
directory. 


Trustee can delete files 
or subdirectories in the 
directory. 


Trustee can grant 
trustee rights to files 
and subdirectories 
in the directory. 


Trustee can scan the 
directory for files and 
subdirectories. 


Trustee can modify file 
and subdirectory attributes 
(hidden, system, sharable, 
etc.) and rename files and 
subdirectories. 


Trustee has all rights to 
the directory. 





When Granted 
for a File 


Trustee can open and 
read the file. 


Trustee can open and 
write to the file. 


Trustee can salvage the 
file after it is deleted. 


Trustee can delete the 


file. 


Trustee can grant 


trustee rights fo the 
file. 


Trustee can see the file 
when scanning the 
directory it is in. 


Trustee can modify the 
file’s attributes (hidden, 
system, shareable, etc.), 
but not its content. 


Trustee has all rights to 


the file. 





As with the NDS tree, trustee rights to directories are inherited down 
the directory tree. Ifyou grant a right to a user in a directory, you do not 
have to explicitly grant the right in its subdirectories. There are two 
ways to block inheritance: 
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Figure 14-6. Using 
Inherited Rights 
Filters to Control File 
Access. 





e You can assign the trustee new rights in a subdirectory. The new rights 


override the inherited rights. 
You can remove rights from the subdirectory’s Inherited Rights Filter. 


Each file and subdirectory has an Inherited Rights Filter (or IRF, also 
called an Inherited Rights Mask) that allows you to specify rights that 
should be blocked, that the file or subdirectory normally would inherit. 
Figure 14-6 illustrates how you can use an IRF to control access to files 
and subdirectories in a file system. 


\ 


es 


USERS DOCS EVERYONE [ RF] 


EVERYONE[ RWCEAFM]| RFC] IRF[ WCEAM ] 
PROJ1 PROJ2 


| > 


IRF[ RWCEAFM ] 
WIP ARCHIVE CONFIDENTIAL 


EVERYONE has all rights EVERYONE has no rights 
except[S ] 
EVERYONE has [ PF ] 
















NetWare 2 and 3 have a utility called SECURITY that checks a file 
server for possible security weaknesses. NetWare 4 instead has an 


extensive system for auditing network events. Some of the things 
SECURITY looks for are: 


e Users whose password is the same as their user name 
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Auditing can be configured 
such that the auditor has 
no access to data on file 
servers, and no user besides 
the auditor (not even user 
Admin) has access to the 
audit files. 


Accounts that are not required to have passwords greater than five 
characters 


Users who are not required to change their password periodically, and 
who are not required to use a unique password when changing their 
password 


Users who have been granted SUPERVISOR equivalence 


Users who have been granted trustee rights to the root directory of any 
volume 


Users who do not have a login script. (The login script is stored in the 
user’s MAIL directory, where all users are allowed to create files. If a 
user does not have a login script, other users could create one for them. 
They could not, however, modify an existing login script.) 


Users who have more than Write and Create rights to another user’s 
MAIL directory 


Users who have been granted rights to the SYS:SYSTEM directory 


Users who have been granted more than Read and File Scan rights to 
the SYS:PUBLIC or SYS:LOGIN directory 


Auditing 





NetWare 4’s auditing system allows you to track and record network 
events. The system is flexible, and can be configured to record just user 
login and logout times, or track every access to every file on a file 
server. Organizations can designate an independent auditor, who is 
separate from the network administrator. Auditing can be configured 
such that the auditor has no access to data on file servers, and no user 
besides the auditor (not even user Admin) has access to the audit files. 
It can also be configured with two-tiered auditing, where one auditor 
reads the audit data, and another auditor configures which events are to 
be audited. 


NetWare auditing was designed to meet the European Information 
Technology (IT) F2 class security standard. 
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Auditor Passwords and 
Audit Keys 


With one-tiered access, a 
single auditor selects which 
events are to be audited 
and generates audit 
reports. With two-tiered 
auditing, the level one 
auditor generates audit 
reports, and the level two 
auditor selects which events 
are to be audited. 


Setting up Auditing 


After logging in to the network, the auditor must log in as the auditor. 
The functions that log in an auditor are NWLoginAsVolumeAuditor and 
NWDSLoginAsContainerAuditor. (Keep reading to learn the difference 
between volume and container auditing.) The login functions return a 
40-byte audit key that your program must pass to all audit functions it 
subsequently calls. After your program has obtained the audit key, it 
should overwrite the auditor password in memory. When your program 
calls NWLogoutAsVolumeAuditor or NWDSLogoutAsContainerAuditor 
the logout function sets the audit key to all zeroes. 


You can configure auditing to have one-tiered or two-tiered access. 
With one-tiered access, a single auditor selects which events are to be 
audited and generates audit reports. With two-tiered auditing, the level 
one auditor generates audit reports, and the level two auditor selects 
which events are to be audited. The level two auditor must first log in as 
a level one auditor. The NWInitAuditLevelTwoPassword function 
enables two-tiered access. 


The only utility Novell provides for auditing is a DOS-based utility 
called AUDITCON. You use AUDITCON to specify which events are to 
be audited, generate audit reports, and maintain audit files. Fortu- 
nately, Novell has also provided all the APIs you need to write your own 
audit utilities for Presentation Manager or your client environment of 
choice. (Did someone say “market opportunity?”) AUDITCON is 
closely coupled with the auditing APIs, so playing with AUDITCON isa 
good way to get familiar with the capabilities of NetWare 4’s auditing 
feature. 


Auditing by volume allows you to audit bindery and file system events. 
Container auditing allows you to audit events related to all objects in a 
container and subordinate containers. You must be equivalent to user 
Admin to set up auditing. The basic algorithm for setting up auditing is 
shown in Figure 14-7. 


The algorithm above applies for the first time you enable auditing on a 
volume or container. The only differences when you are reconfiguring 
auditing is that the first call to NWLoginAsVolumeAuditor or 
NWDSLoginAsContainerAuditor will not fail and you will not call the 
function to enable auditing (NWEnableAuditingOnVolume or NWDS- 
EnableAuditingOnContainer). 
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IF enabling volume auditing 


call NWLoginAsVolumeAuditor (the function will return 0x8997 
“Auditing Not Enabled”) 


IF using two-tiered audit access 
call NWInitAuditLevelTwoPassword to activate two-tiered securing 


call NWEnableAuditingOnVolume 
call NWLoginAsVolumeAuditor again to login as volume auditor 


IF you want to change any auditing parameter fields in the 
configuration to a value other than default 


call NWReadAuditConfigHeader to get the configuration header 

Set auditing parameter fields in the configuration header to 
desired values 

call NWWriteAuditConfigHeader to set header fields to their new 
values 


Set bits in the auditing bitmap according to which events are to 
be audited (bitmap should be all zeroes the first time auditing is 
configured, so you do not have to read the bitmap values before 
setting the new values) 

call NWWriteAuditingBitMap to write the auditing bit map to the 


configuration header 


IF you want to audit file events related to a specific user 
| call NWSetFileInformation2 to set the file’s auditing bit 


call NWLogoutAsVolumeAuditor to logout as auditor 


ELSE if enabling container auditing 





call NWDSLoginAsContainerAuditor (the function will return 0x8997 
“Auditing Not Enabled”) 


IF using two-tiered auditing access 
| call NWInitAuditLevelTwoPassword to activate tow-tiered security 


call NWDSEnableAuditingOnContainer 
call 


Figure 12") Hoan 11 NWDSLoginAsContainerAuditor again to login as container auditor 


Algorithm for 
Setting up 
Auditing. 
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Figure 14-7. Basic 
Algorithm for Setting 
up Auditing. 
(Continued) 


Configuration Header 


IF you want to change any auditing parameter fields in the 
configuration to a value other than the default 


call NWReadAuditConfigHeader to get the configuration header 

set auditing parameter fields in the configuration header to 
desired values 

call NWWriteAuditConfigHeader to set header fields to their new 
values 


set bits in the auditing bitmap according to which events are to be 
audited (bitmap should be all zeroes the first time auditing is 
configured, so you do not have to read the bitmap before setting 
the new values) 


call NWWriteAuditingBitMap to write the auditing bitmap to the 
configuration header 


IF you want to audit file events related to a specific object 
| call NWAddAuditProperty to add an audit property to the object 


IF you want to audit events related to a specific file 
| call NWSetFileInformation2 to set the file’s auditing bit 


call NWDSLogoutAsContainerAuditor to logout as auditor 


The audit file configuration header contains the parameters that control 
auditing on a volume or container. The two most important fields in the 
header are the event bitmap, which determines which events will be 
audited, and the audit flags, which enables several auditing features. 
The configuration headers for volumes and containers are slightly 
different. The configuration header for a volume is declared as shown 
below, followed by descriptions of each of the fields: 
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typedef struct 
{ 


WORD fileVersionDate; 

BYTE auditFlags; 

BITE errMsgDelayMinutes; 

BYTE reservedl1l6]; 

LONG volumeAuditFileMaxSize; 

LONG volumeAuditFileSizeThreshold; 
LONG auditRecordCount; 

LONG historyRecordCount; 

LONG spareLongs[/7]; 


NWAuditBitMap volumeAuditEventBitMap; 
} NWConfigHeader; 


fileVersionDate is the version of the audit file (used internally by 
NetWare to identify the version of the audit feature that created the 
file). 


auditFlags is a set of bit flags that enable auditing features (see Figure 
14-8 for a description of the flags). 


Bit Field Name If Set 
DiscardAuditRcdsOnErrorFlag Auditing records are discarded if an 
error occurs. 


ConcurrentVolAuditorAccess More than one auditor can log in to 
the object at a time. 


DualLevelPasswordActive Two-tier auditing is enabled. 
BroadcastWarningToAllUsers 


LevelTwoPasswordSet 























The level 2 password has been set. 
This flag cannot be modified, and is 


Figure 14-8. . rar 
Description of Flags meaningful only if bit 2 
in the auditFlags Field Is set. 
of an Audit 


Configuration Header. 
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errMsgDelayMinutes is the number of minutes to delay when sending 
error messages to users that the audit file is reaching maximum size. 


volumeAuditFileMax is the maximum allowable size of the audit file. 


volumeAuditFileThreshold is the size at which NetWare will start notify-_ 
ing users that the audit file is reaching maximum size. 


auditRecordCount is the number of records in the audit file. 


volumeAuditEventBitMap is a 64-byte (512-bit) field specifying which 
events to audit. See the NetWare Programmer’s Guide for C in the 
NetWare Client SDK for documentation of each of the bits in the 
bitmap. 


The configuration header for a container is declared as shown below, 
followed by descriptions of each of the fields: 


typedef struct audit_container_file_hdr 
{ 
WORD fileVersionDate; 
BYTE auditFlags; 
BYTE errMsgDelayMinutes; 
LONG containerID; 
LONG SpareLongO; 
TIMESTAMP creationls; 
LONG bitMap; 
LONG auditFileMaxSize; 
LONG auditFileSizelhreshold; 
LONG auditRecordCount; 
WORD replicaNumber; 
BYTE enabledFlag; 
BYTE SpareBytesLl3]; 
WORD numberReplicaEntries; 
LONG SpareLongsL9]; 
LONG auditDisabledCounter; 
LONG auditEnabledCounter; 
BITE reserved[32]; 
LONG hdrModifiedCounter; 
LONG fileResetCounter; 
} NWDSContainerConfigHdr; 
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The /fileVersionDate, auditFlags, errMsgDelayMinutes, and 
auditRecordCount fields are the same as for the volume configuration 
header. 


containerID is NDS’s identifier for the container. 
creationTS is the date and time the audit file was created. 


bitMap is a 32-bit field specifying which events to audit. See the NetWare 
Programmer's Guide for C in the NetWare Client SDK for documentation 
of each of the bits in the bitmap. 


auditFileMaxSize is the maximum allowable size of the audit file. 


auditFileSizeThreshold is the size at which NetWare will start notifying 
users that the audit file is reaching maximum size. 


replicaNumber identifies the NDS partition replica on which the event 
occurred. 


enabledFlag is a flag that is set when auditing is enabled on the con- 
tainer. 


numberReplicaEntries is the number of partition replicas on which the 
event was replicated. 


auditDisabledCounter, auditEnabledCounter, hdrModifiedCounter, and 
fileResetCounter are used internally by the audit system. 


Fvent Records To create a report of audited events, first call NWinitAuditFileRead and 
pass NW_AUDIT_FILE_CODE to the function’s fileCode parameter, 
and the volume ID or container ID of the object you want to audit to the 
volumeContainerld parameter. Then call NWReadAuditingFileRecord 
repeatedly (passing the same parameters to the fileCode and 
volumeContainerID parameters) to read event records from the audit 
file, until the function returns a non-zero value in the eofFlag parameter. 
You will need to pass a pointer to a 512-byte buffer in the buffer 
parameter. Each time you call the function, it will return one event 
record in the buffer. If you are auditing a volume, the buffer contains an 
auditRcd structure; if you are auditing a container, the buffer contains a 
auditDSRcd structure. The declaration of the auditRcd structure is 
shown below, followed by descriptions of its fields: 
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Struct auditRcd 
{ 
WORD eventlypelID; 
WORD chkWord; 
LONG connectionlD; 
LONG processUniquelD; 
LONG SuccessFailureStatusCode; 
WORD dosDate; 
WORD dosTime; 
/* BYTEextrald]; Start of ‘union 
EventUnion’ */ 
ie 


eventTypelD identifies the type of the event record. 
chkWord is a checksum value, used internally by the audit system. 


connectionID is the connection ID of the NetWare server on which the 
event occurred. 


processUniquelD is the bindery object ID of the object that performed 
the event. 


successFailureStatusCode is the terminating status of the event; 0 = 
success, 1 = failure. 


dosDate and dosTime are the date and time the event occurred, in DOS 
date and time format. 


The declaration of the auditDSRcd structure is shown below, followed 
by descriptions of its fields: 


SLruct auditDsked 
{ 
WORD replicaNumber; 
WORD eventlypelD; 
LONG recordNumber ; 
LONG dosDatelime; 
LONG userID; 
LONG processUniquelD; 
LONG successFailureStatusCode; 
k* BYTE@xKtralol: Start of ‘union 
EventUnion’ */ 
ie 
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Audit History 


replicaNumber identifies the NDS partition replica on which the event 
occurred. 


eventTypelD identifies the type of the event record. 
recordNumber is the number of this record in the record file. 


dosDateTime is the date and time the event occurred, in DOS date/time 
format. 


userID is the user who performed the event. 


processUniquelD is the NDS object ID of the object that performed the 
event. 


successFailureStatusCode is the terminating status of the event; 0 = 
success, 1 = failure. 


The area in the buffer following the audit record is event-specific data. 
By checking the eventTypelID field in the audit record, you can apply 
the appropriate structure from the EventUnion to interpret the data that 
follows the audit record. For example, if the eventTypeID is 21 
(A_EVENT_LOGIN_USER), the following structure follows the audit 
record in the buffer: 


struct eventLogin 


{ 
LONG userlID; 
BYTE networkAddresslType; 
BYTE networkAddressLength; 
BYTE networkAddress[Ll];/* variable length */ 
BYTE nameLl]; 
; ELoST th: 


See the NetWare Programmer’s Guide for C in the NetWare Client SDK 
for a list of the event type Ids and documentation of EventUnion. 


Besides the audit file for volumes or containers, the auditing system 
maintains records of events relating to the auditing system itself. Some 
of the audit history events the auditing system keeps track of are: 
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auditor login 

auditor user added 

audit password changed 

auditing enabled on a volume or container 

audit file reset 

audit bitmap changed 

audit file configuration header changed 

For containers, audit history records are stored in the audit file; for 
volumes, there is an audit history file. To read audit history events, call 
NWInitAuditFileReads and pass NW_AUDIT_HISTORY_FILE_CODE 
to the function’s fileCode parameter. Then call 
NWReadAuditingFileRecord repeatedly until the eofFlag parameter is 


set to a non-zero value. Audit history event records have the same 
structure as volume event records. 
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And how his audit stands, who knows save heaven? 


—Shakespeare, Hamlet 


As we mentioned in the previous chapter, NetWare 4’s audit feature can 
be configured to audit many network events, including 


Creating and deleting bindery object 
Logging in 

Creating, deleting, or opening a file 
Changing a password 


Placing a job in a queue 
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The DOS utility AUDITCON is the only utility Novell provides to 
manage auditing and generate audit reports. The utility presented in 
this chapter illustrates how to report audited events for a volume. The 
concepts introduced by this utility could be the basis of an OS/2-based 
audit utility. 


i) 


AUDITVOL reports on audited events for a volume. Figure 15-1 de- 
scribes the functionality and simplifying assumptions used in 
AUDITVOL. You must configure auditing and enable auditing for 
volume events before running AUDITVOL. Pseudocode for AUDITVOL 
is given in Figure 15-2. 


PROGRAM: AUDITVOL.EXE 

DESCRIPTION: Generate a report of audited events for 
a volume. 

SYNTAX: AUDITVOL volumeName 

REMARKS: If volumeName is not specified, 


generates its report for volume of the 
default drive. 


SIMPLIFYING 
ASSUMPTIONS: « We do not try to interpret all the 
event-specific data for each event 
Figure 15-1. record : 

Description and 
Simplifying 
Assumptions for 
AUDITVOL.EXE. 


After getting the auditor password from the user and logging in as the 
volume auditor, your program should immediately erase the auditor 
password from memory. Passwords are encrypted before they are sent 
across the network, but if they are left in memory, they are vulnerable to 
viruses or Trojan Horse programs. 
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Figure 15-2. Pseudo- 
code for AUDITVOL. 


initialize NWCalls interface 
get connection ID of default file server 


IF a volume name was specified on the command line 
use specified volume name 
ELSE 
use the volume to which the default drive is mapped 
get volume auditor password 
login as volume auditor 
erase volume auditor password from memory 
read and display volume audit configuration 
read and display volume audit statistics 
display which events are being audited 
LOOP 
get audit event record 
display audit event record 
LOOP 
get audit history record 


display audit history record data 


logout as volume auditor 


Figure 15-3 lists the source code for AUDITVOL. The 
PrintAuditedEvents and PrintEventInformation functions are abbrevi- 
ated, because they are only large if or switch statements that display a 
string based on the value of a parameter. 
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fHinclude <stdio.h> 
fHinclude <stdlib.h> 
fHinclude <stdarg.h> 
#include <ctype.h> 
#Hinclude <conio.h> 
fHinclude <string.h> 
define IS32BIT 
define BCPP 
#include <nwcalls.h> 
#Hinclude <nwnet.h> 
#Finclude <nwaudit.h> 
fHinclude <nwmisc.h> 


void Usage(void); 
void PrintAuditedEvents(BYTE *bitmap) ; 
void PrintEventInformation(WORD eventTypelID, union EventUnion *eventInfo); 


void main (int argc, char **argv) 
{ 


NWCCODE ccode; 

WORD driveStatus; 
char drivePath[255]; 
char volumeNameL1/7]; 
NWVOL_NUM volumeNumber; 
NWCONN_HANDLE conn; 

int 1S 

char ch; 

char password[ 255]; 
BYTE auditKey[40]; 
NWConfigHeader configHeader; 
NWVolumeAuditStatus auditStatus ; 

BYTE auditRecord[512]; 
WORD recordSize; 
BYTE eof; 

NW_DATE theDate; 

NW_TIME thelime; 


union EventUnion *eventInfo; 


ccode = NWCallsInit(NULL, NULL); 

if (ccode != SUCCESSFUL) 

| 
printf(“Unable to initialize NetWare interface\n”); 
exit(-1); 


/* get connection ID of default file server */ 


Figure 15-3. Listing of 
AUDITVOL.C. 
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ccode = 


NWGetDefaultConnectionID(&conn); 


if (ccode != SUCCESSFUL) 


{ 


printf(“Unable to get connection I[D\n”); 
Sxith-1Li}3 


if (argc == 1) 


{ 


ccode = 


/* volume name not specified */ 

ccode = NWGetDriveStatus(0, NW_FORMAT_NETWARE, &driveStatus, NULL, 
drivePath, NULL, NULL); 

if ((ccode != SUCCESSFUL) || (!(driveStatus & NW_NETWARE_DRIVE))) 


Usage(); 
exits 1): 
} 
else 
{ 
ccode = NWParsePath(drivePath, NULL, &conn, volumeName, NULL); 
if (ccode != SUCCESSFUL) 
{ 
printf(“Unable to parse path of default drive\n”); 
exit(-1); 
} 
} 
(argc == 2) 


/* volume name specified */ 
Strcpy(volumeName, argv[1l]); 


Usage(); 
exit(-1); 


NWGetVolumeNumber(conn, volumeName, &volumeNumber): 


it Cccode f= SUCCESSFUL) 


printf(“Unable to get volume number of volume %s\n”, volumeName) ; 
exitt(<-1); 


Figure 15-3. Listing of 


AUDITVOL.C. 
(Continued) 
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printf(“Enter auditor password for volume 4s: “, volumeName) ; 
i=0; 
do 
{ 
ch=getch(); 
if (ch l= “i\r") 


{ 
passwordLi] = toupper(ch); 
hae or 
putch( ***); 
} 
} while (ch != ‘\r’); 
passwordli] = *\0°; 
printf(“\n"); 


ccode = NWLoginAsVolumeAuditor(conn, volumeNumber, auditKey, 


(BYTE *)password); 

if (ccode != SUCCESSFUL) 

{ 
printf(“Unable to log in as volume auditor, ccode = 4Xh\n”, ccode); 
exitti-1)% 


/* get password out of memory */ 
memset(password, 0, strlen(password)); 
ccode = NWReadAuditConfigHeader(conn, volumeNumber, auditKey, &configHeader, 


Sizeof(configHeader)); 
if (ccode != SUCCESSFUL) 
printf(“Unable to read volume’s audit configuration header, ccode = 4Xh\n”, 
ccode); 
else 


printf(“Volume audit configuration: \n”); 

if (configHeader.auditFlags & DiscardAuditRcdsOnErrorFlag) 
printf(“\tDiscard audit records on error\n”); 

else 
printf(“\tDo not discard audit records on error\n”); 


if (configHeader.auditFlags & ConcurrentVolAuditorAccess) 
printf(“\tConcurrent volume auditor access\n”); 
else 
printf(“\tNo concurrent volume auditor access\n”); 


Figure 15-3. Listing of 
AUDITVOL.C. 
(Continued) 
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if (configHeader.auditFlags & DualLevelPasswordsActive) 
printf(“\tDual level passwords active\n”); 

else 
printf(“\tDual level passwords not active\n”); 


if (configHeader.auditFlags & BroadcastWarningsToAllUsers) 
printf(“\tBroadcast warnings to all users\n”); 

else 
printf(“\tNo not broadcast warnings to all users\n”); 


if (configHeader.auditFlags & LevelTwoPasswordSet) 
printf(“\tLevel two password is set\n”); 
else 
printf(“\tLevel two password is not set\n”); 


printf(“\tVolume audit file maximum size: 41d bytes\n”, 
configHeader.volumeAuditFileMaxSize); 
printf(“\tVolume audit file threshold size (file size beyond which AUDITCON sends\n”); 
printf(“\t\twarnings to the server console and log file: 41d bytes\n”, 
configHeader.volumeAuditFileSizeThreshold); 
printf(“\tNumber of audit records: %41d\n”, configHeader.auditRecordCount) ; 
printf(“\tNumber of history records: 41d\n”, configHeader.historyRecordCount) ; 
ccode = NWGetVolumeAuditStats(conn, volumeNumber, &auditStatus, sizeof(auditStatus) ); 
if (ccode != SUCCESSFUL) 
printf(“Unable to get volume audit statistics\n”); 
else 
printf(“\tVolume’s audit file size: 41d bytes\n”, auditStatus.volumeAuditFileSize) ; 


printf(“\tAudited events:\n”); 
PrintAuditedEvents(configHeader.volumeAuditEventBitMap.bitMap) ; 
HPinET CT A Pe 


/* see if the user wants to view the contents of the audit file */ 


do 

{ 
printf(“View contents of audit file? (y/n): “); 
ch = toupper(getche()); 
princi \a'); 

} while ((ch != ‘Y’) && (ch != ‘N’)); 

if (ch == ‘Y’) 


{ 
ccode = NWInitAuditFileRead(conn, volumeNumber, NW_AUDIT_FILE_CODE, 0): 


Figure 15-3. Listing of 
AUDITVOL.C. 
(Continued) 
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1? (eeode t= SUCCESSFUL) 
printf(“Unable to read audit file\n”); 


else 
{ 
do 


Sizeof(auditRecord), &eof); 


>dosDate, &theDate); 


theDate.day, theDate.year); 


>dosTime, &theTime); 


thelTime.minutes, 


theTime.seconds); 


a 


sizeof(AuditRecord)); 


>eventlypelD, 


Figure 15-3. Listing of 
AUDITVOL.C. 
(Continued) 


ccode = NWReadAuditingFileRecord(volumeNumber, NW_AUDIT_FILE_CODE, 
&auditRecord, &recordSize, 


if (ccode != SUCCESSFUL) 
printf(“Failure reading audit file\n”); 
break; 

} 

else if (!eof) 

{ 


if (((AuditRecord *)auditRecord)->dosDate != OL) 
{ 
NWUnpackDate(((AuditRecord *)auditRecord) - 
printf(“%02d/%02d/%02d “, theDate.month, 
} 
else 
printet™ ce Be 
if (((AuditRecord *)auditRecord)->dosTime != OL) 
{ 
NWUnpackTime(((AuditRecord *)auditRecord) - 


printf(“Z02d:%202d:202d “, thelime.hours, 


else 
printf (“ ape 


/* point to end of auditRecord to get event-specific data 


eventInfo = (union EventUnion *)(auditRecord + 


PrintEventInformation(((AuditRecord *)auditRecord) - 
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eventInfo); 
} 
} while (!eof); 


/* see if the user wants to view the contents of the audit history file */ 


do 

{ 
printf(“View contents of audit history file? (y/n): “); 
ch = toupper(getche()); 
PPINTT EAA" 2s 

} while ((ch != ‘Y’) && (ch != ‘N’)); 

if (ch == ‘Y’) 


{ 
ccode = NWInitAuditFileRead(conn, volumeNumber, NW_AUDIT_HISTORY_FILE_CODE, 0); 


if (ccode != SUCCESSFUL) 
printf(“Unable to read audit history file\n”); 


do 


ccode = NWReadAuditingFileRecord(volumeNumber, NW_AUDIT_HISTORY_FILE_CODE, 
&auditRecord, 


&recordSize, sizeof(auditRecord), &eof); 
if (ccode != SUCCESSFUL) 


{ 
printf(“Failure reading audit file\n”); 


break; 


} 
else if (!eof) 
{ 


/* point to end of auditRecord to get event-specific data */ 
eventInfo = (union EventUnion *)(auditRecord + 


sizeof(AuditRecord)); 


PrintEventInformation(((AuditRecord *)auditRecord)->eventTypelD, 


eventInfo); 
} 
} while (!eof); 


ccode = NWLogoutAsVolumeAuditor(conn, volumeNumber, auditKey); 


Figure 15-3. Listing of 
AUDITVOL.C. 
(Continued) 
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if (ccode != SUCCESSFUL) 
printf(“Volume auditor logout failed\n”); 


void Usage(void) 
{ 
printf(“usage: AUDITVOL [<volumeName>]\n”); 
printf(“If volumeName is not specified, volume of default drive is used\n”); 


void PrintAuditedEvents(BYTE *bitmap) 
{ 
/* Check bits of the volumeAuditedEventBitmap by selecting a byte in the bitmap, 
then ORing to see if a bit in that byte is set */ 
if (bitmapLA_BIT_BIND_CHG_OBJ_SECURITY/8] & (1<<(A_BIT_BIND_CHG_OBJ_SECURITY2Z8) )) 
printf(“\t\tBindery object security changed\n”); 
if (bitmapLA_BIT_BIND_CHG_PROP_SECURITY/8] & (1<<(A_BIT_BIND_CHG_PROP_SECURITY%8) ) ) 
printf(“\t\tBindery property security changed\n”) ; 
if (bitmapLA_BIT_BIND_CREATE_OBJ/8] & (1<<(A_BIT_BIND_CREATE_OBJ28) ) ) 
printf(“\t\tBindery object changed\n”); 
if (bitmapLA_BIT_BIND_CREATE_PROPERTY/8] & (1<<(A_BIT_BIND_CREATE_PROPERTY2Z8) ) ) 
printf(“\t\tBindery object property created\n”); 
if (bitmapLA_BIT_BIND_DELETE_OBJ/8] & (1<<(A_BIT_BIND_DELETE_OBJ%8) ) ) 
printf(“\t\tBindery object deleted\n”); 
if (bitmapLA_BIT_BIND_DELETE_PROPERTY/8] & (1<<(A_BIT_BIND_DELETE_PROPERTY%8) ) ) 
printf(“\t\tBindery object property deleted\n”); 
if (bitmapCLA_BIT_CHANGE_DATE_TIME/8] & (1<<(CA_BIT_CHANGE_DATE_TIME%8) )) 
printf(“\t\tFile server date and time changed\n”); 
if (bitmapLA_BIT_CHANGE_EQUIVALENCE/8] & (1<<(CA_BIT_CHANGE_EQUIVALENCE%8) ) ) 
printf(“\t\tBindery object security equivalence changed\n”) ; 
if (bitmapLA_BIT_CHANGE_SECURITY_GROUP/8] & (1<<(A_BIT_CHANGE_SECURITY_GROUPZ8) ) ) 
printf(“\t\tBindery group membership changed\n”); 
if (bitmapLA_BIT_UCLOSE_FILE/8] & (1<<(A_BIT_UCLOSE_FILEZ8) )) 
printf(“\t\tAudited file opened OR audited user opened a file\n”); 
if (bitmapLA_BIT_CLOSE_BINDERY/8] & (1<<(A_BIT_CLOSE_BINDERY2Z8) ) ) 
printf(“\t\tBindery closed\n”); 
if (bitmapLA_BIT_UCREATE_FILE/8] & (1<<(A_BIT_UCREATE_FILE%8) ) ) 
printf(“\t\tAudited file created OR audited user created a file\n”); 
if (bitmapLA_BIT_CREATE_USER/8] & (1<<(A_BIT_CREATE_USERZ8) ) ) 
printf(“\t\tUser created\n”); 
if (bitmapCA_BIT_UDELETE_FILE/8] & (1<<(A_BIT_UDELETE_FILE%8) ) ) 
printf(“\t\tAudited file deleted OR audited user deleted a file\n”); 
if (bitmapCLA_BIT_DELETE_USER/8] & (1<<(A_BIT_DELETE_USERZ8) ) ) 
printf(“\t\tUser deleted\n”) ; 
if (bitmapCA_BIT_DIR_SPACE_RESTRICTIONS/8] & (1<<(A_BIT_DIR_SPACE_RESTRICTIONS2Z8) ) ) 


Figure 15-3. Listing of 
AUDITVOL.C. 
(Continued) 


216 OS/2 and NetWare Programming: Using the NetWare Client API for C 


printf(“\t\tDirectory space restrictions set\n”); 

if (bitmapLA_BIT_DISABLE_ACCOUNT/8] & (1<<(A_BIT_DISABLE_ACCOUNT28) ) ) 
printf(“\t\tAccount disabled\n”); 

if (bitmapCLA_BIT_DOWN_SERVER/8] & (1<<(A_BIT_DOWN_SERVERZ8) ) ) 
printf(“\t\tServer downed\n”); 

if (bitmapLA_BIT_GRANT_TRUSTEE/8] & (1<<(A_BIT_GRANT_TRUSTEE%8) ) ) 
printf(“\t\tTrustee rights granted\n”); 

if (bitmapLA_BIT_INTRUDER_LOCKOUT_CHANGE/8] & (1<<(A_BIT_INTRUDER_LOCKOUT_CHANGE%S8) ) ) 
printf(“\t\tIntruder lockout status changed\n”); 

if (bitmapCLA_BIT_LOGIN_USER/8] & (1<<(CA_BIT_LOGIN_USERZ%8) )) 
printf(“\t\tUser logged in\n”); 

if (bitmapCA_BIT_LOGIN_USER_FAILURE/8] & (1<<(A_BIT_LOGIN_USER_FAILUREZ8) ) ) 
printrc*Ve\tUser login failed\n”)s 

if (bitmapLA_BIT_LOGOUT_USER/8] & (1<<(A_BIT_LOGOUT_USERZ8) ) ) 
printt¢"\tituser logged cut\n”); 

if (bitmapLA_BIT_NET_LOGIN/8] & (1<<(A_BIT_NET_LOGINZ8) )) 
printf(“\t\tNet login\n”); 

if (bitmapCA_BIT_UMODIFY_ENTRY/8] & (1<<(A_BIT_UMODIFY_ENTRY%8) ) ) 
printf(“\t\tAudited directory entry modified OR audited user modified a directory 

entry\n”); 

if (bitmapCA_BIT_OPEN_BINDERY/8] & (1<<(A_BIT_OPEN_BINDERY2%8) ) ) 
printf(“\t\tBindery opened\n”) ; 

if (bitmapCLA_BIT_UOPEN_FILE/8] & (1<<(A_BIT_UOPEN_FILE%8) )) 
printf(“\t\tAudited file opened OR audited user opened a file\n”); 

if (bitmapCLA_BIT_UREAD_FILE/8] & (1<<(A_BIT_UREAD_FILE%8) )) 
printf(“\t\tAudited file read OR audited user read a file\n”); 

if (bitmapCA_BIT_REMOVE_TRUSTEE/8] & (1<<(A_BIT_REMOVE_TRUSTEE%8) )) 
printf(“\t\tTrustee rights removed\n”) ; 

if (bitmapCA_BIT_URENAME_MOVE_FILE/8] & (1<<(A_BIT_URENAME_MOVE_FILEZ8) ) ) 
printf(“\t\tAudited file renamed or moved OR audited user renamed or moved a 


if (bitmapCLA_BIT_RENAME_USER/8] & (1<<(A_BIT_RENAME_USERZ8) ) ) 
printf(“\t\tUser renamed\n”); 

if (bitmapLA_BIT_USALVAGE_FILE/8] & (1<<(A_BIT_USALVAGE_FILE%8) ) ) 
printf(“\t\tAudited file salvaged OR audited user salvaged a file\n”); 

if (bitmapLA_BIT_STATION_RESTRICTIONS/8] & (1<<(A_BIT_STATION_RESTRICTIONS%8) ) ) 
DrintrhC"\CAEStation restrictions setin”); 

if (bitmapLA_BIT_CHANGE_PASSWORD/8] & (1<<(A_BIT_CHANGE_PASSWORD2Z8) ) ) 
printf(“\t\tPassword changed\n”) ; 

if (bitmapLA_BIT_TERMINATE_CONNECTION/8] & (1<<CA_BIT_TERMINATE_CONNECTION%8) ) ) 
printf(“\t\tConnection terminated\n”) ; 

if (bitmapLA_BIT_UP_SERVER/8] & (1<<(A_BIT_UP_SERVERZ8) ) ) 
printf(“\t\tServer brought up\n”); 

if (bitmapLA_BIT_USER_CHANGE_PASSWORD/8] & (1<<(A_BIT_USER_CHANGE_PASSWORD%8) ) ) 
printf(“\t\tUser changed password\n”); 


Figure 15-3. Listing of 
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if (bitmapLA_BIT_USER_LOCKED/8] & (1<<(A_BIT_USER_LOCKEDZ8) ) ) 
printf(“\t\tUser account locked\n”); 

if (bitmapLA_BIT_USER_SPACE_RESTRICTIONS/8] & (1<<(A_BIT_USER_SPACE_RESTRICTIONSZ8) ) ) 
printf(“\t\tUser space restricted on volume\n”); 

if (bitmapCA_BIT_USER_UNLOCKED/8] & (1<<(A_BIT_USER_UNLOCKED2Z8) ) ) 
printf(“\t\tUser account unlocked\n”); 

if (bitmapLA_BIT_VOLUME_MOUNT/8] & (1<<(CA_BIT_VOLUME_MOUNTZ8) ) ) 
printf(“\t\tVolume mounted\n”) ; 

if (bitmapCA_BIT_VOLUME_DISMOUNT/8] & (1<<(A_BIT_VOLUME_DISMOUNT28) ) ) 
printf(“\t\tVolume dismounted\n”); 

if (bitmapCA_BIT_UWRITE_FILE/8] & (1<<(A_BIT_UWRITE_FILE%8) )) 
printf(“\t\tAudited file written OR audited user wrote a file\n”); 

if (bitmapLA_BIT_GOPEN_FILE/8] & (1<<(A_BIT_GOPEN_FILE%8) )) 
printf(“\t\tFile opened\n”) ; 

if (bitmapLA_BIT_GCLOSE_FILE/8] & (1<<(A_BIT_GCLOSE_FILEZ8) )) 
printt( “\t\iFile closed\n”"); 

if (bitmapLA_BIT_GCREATE_FILE/8] & (1<<(A_BIT_GCREATE_FILE%8) ) ) 
printf(“\t\tFile created\n”); 

if (bitmapCA_BIT_GDELETE_FILE/8] & (1<<(A_BIT_GDELETE_FILE%8) ) ) 
printf(“\t\tFile deleted\n”); 

if (bitmapCA_BIT_GREAD_FILE/8] & (1<<(A_BIT_GREAD_FILE%8) )) 
pPIntT( *\EATFI le redd\n"); 

if (bitmapCA_BIT_GWRITE_FILE/8] & (1<<(A_BIT_GWRITE_FILE%8) )) 
printf(“\t\tFile written\n”); 

if (bitmapCA_BIT_GRENAME_MOVE_FILE/8] & (1<<(A_BIT_GRENAME_MOVE_FILE%8) )) 
printf(“\t\tFile renamed or moved\n”); 

if (bitmapCA_BIT_GMODIFY_ENTRY/8] & (1<<(A_BIT_GMODIFY_ENTRY%8) ) ) 
printf(“\t\tDirectory entry modified\n”); 

if (bitmapCA_BIT_IOPEN_FILE/8] & (1<<(A_BIT_IOPEN_FILE%8) ) ) 
printf(“\t\tAudited user opened an audited file\n”); 

if (bitmaplA BIT_ICLOSE_FILE/8] & (1<<(A_BIT_ICLOSE FILERB))) 
printf(“\t\tAudited user closed an audited file\n”); 

if (bitmapLA_BiT_IVELETE_LFILE/8J & (1<<CA_BIT_IDELETE_FILESS))) 
printf(“\t\tAudited user deleted an audited file\n”); 

if (bitmapCA_BIT_IREAD_FILE/8] & (1<<(A_BIT_IREAD_FILE%8) ) ) 
printf(“\t\tAudited user read an audited file\n”); 

if (bitmapCA_BIT_IWRITE_FILE/8] & (1<<(A_BIT_IWRITE_FILE%8) )) 
printf(“\t\tAudited user wrote an audited file\n”); 

if (bitmapCA_BIT_IRENAME_MOVE_FILE/8] & (1<<(A_BIT_IRENAME_MOVE_FILE%8) )) 
printf(“\t\tAudited user renamed or moved an audited file\n”); 

if (bitmapLA_BIT_IMODIFY_ENTRY/8] & (1<<(A_BIT_IMODIFY_ENTRY%8) ) ) 
printf(“\t\tAudited user modified an audited directory entry\n”); 

if (bitmaplLA_BIT_Q_ATTACH_SERVER/8] & (1<<(A_BIT_Q_ATTACH_SERVER%8) ) ) 
printf(“\t\tQueue server attached to queue\n”); 

if (bitmaplA_BIT_Q_CREATE/8] & (1<<(A_BIT_Q_CREATE%8) ) ) 
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printfc*\t\tQuewe created\n”); 

if (bitmapLA_BIT_Q_CREATE_JOB/8] & (1<<(A_BIT_Q_CREATE_JOB2Z8) ) ) 
printf(“\t\tQueue job created\n”); 

if (bitmapCLA_BIT_Q_DESTROY/8] & (1<<(A_BIT_Q_DESTROY2Z8) ) ) 
printf(“\t\tQueue destroyed\n”); 

if (bitmapCA_BIT_Q_DETACH_SERVER/8] & (1<<(A_BIT_Q_DETACH_SERVER%8) ) ) 
printf(“\t\tQueue server detached from queue\n”); 

if (bitmapCA_BIT_Q_EDIT_JOB/8] & (1<<(A_BIT_Q_EDIT_JOBZ8) ) ) 
printf(“\t\tQueue job configuration changed\n”) ; 

if (bitmapCLA_BIT_Q_JOB_FINISH/8] & (1<<(A_BIT_Q_JOB_FINISHZ8) ) ) 
printf(“\t\tQueue server finished servicing a job\n”); 

if (bitmapCA_BIT_Q_JOB_SERVICE/8] & (1<<(A_BIT_Q_JOB_SERVICE%8) ) ) 
printf(“\t\tQueue server accepted a job for service\n”); 

if (bitmapLA_BIT_Q_JOB_SERVICE_ABORT/8] & (1<<(A_BIT_Q_JOB_SERVICE_ABORTZ8) ) ) 
printf(“\t\tQueue server aborted servicing a job\n”); 

if (bitmapCLA_BIT_Q_REMOVE_JOB/8] & (1<<(A_BIT_Q_REMOVE_JOB2Z8) ) ) 
printf(“\t\tdJob removed from queue\n”); 

if (bitmapCA_BIT_Q_SET_JOB_PRIORITY/8] & (1<<(A_BIT_Q_SET_JOB_PRIORITY%8) ) ) 
printf(“\t\tPriority set on queue job\n”); 

if (bitmapCLA_BIT_Q_SET_STATUS/8] & (1<<(A_BIT_Q_SET_STATUS2%8) ) ) 
printf(“\t\tQueue status set\n”); 

if (bitmapLA_BIT_Q_START_JOB/8] & (1<<(A_BIT_Q_START_JOB%8) ) ) 
printf(“\t\tdJob released to queue\n”); 

if (bitmapCA_BIT_Q_SWAP_RIGHTS/8] & (1<<(A_BIT_Q_SWAP_RIGHTSZ8) ) ) 
printf(“\t\tQueue server assumed client rights\n”); 

if (bitmapCLA_BIT_NLM_ADD_RECORD/8] & (1<<(A_BIT_NLM_ADD_RECORD%8) ) ) 
printf(“\t\tNLM added an audit record\n”); 

if (bitmapCA_BIT_NLM_ADD_ID_RECORD/8] & (1<<(A_BIT_NLM_ADD_ID_RECORD%8) ) ) 
printf(“\t\tNLM added a user ID record\n”); 

if (bitmapCLA_BIT_CLOSE_MODIFIED_FILE/8] & (1<<(A_BIT_CLOSE_MODIFIED_FILE%8) )) 
printf(“\t\tModified file closed\n”); 

if (bitmapLA_BIT_GCREATE_DIRECTORY/8] & (1<<(A_BIT_GCREATE_DIRECTORY%8) ) ) 
printf(“\t\tSubdirectory created\n”); 

if (bitmapLA_BIT_ICREATE_DIRECTORY/8] & (1<<(A_BIT_ICREATE_DIRECTORY%8) ) ) 
printf(“\t\tAudited user created an audited subdirectory\n”); 

if (bitmapLA_BIT_UCREATE_DIRECTORY/8] & (1<<(A_BIT_UCREATE_DIRECTORY2%8) ) ) 
printf(“\t\tAudited directory created OR audited user created a directory\n”); 

if (bitmapLA_BIT_GDELETE_DIRECTORY/8] & (1<<(A_BIT_GDELETE_DIRECTORY2%8) ) ) 
printf(“\t\tDirectory deleted\n”); 

if (bitmapCLA_BIT_IDELETE_DIRECTORY/8] & (1<<(A_BIT_IDELETE_DIRECTORY%8) ) ) 
printf(“\t\tAudited user deleted an audited subdirectory\n”); 
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if (bitmapLA_BIT_UDELETE_DIRECTORY/8] & (1<<(A_BIT_UDELETE_DIRECTORY%8) ) ) 
printf(“\t\tAudited directory deleted OR audited user deleted a directory\n”) ; 


void PrintEventInformation(WORD eventTypelID, union EventUnion *eventInfo) 
{ 

NW_DATE theDate; 

NW_TIME theTime; 


Switch (eventTypelID) 
{ 
case A_EVENT_BIND_CHG_OBJ_SECURITY 
printf(“Bindery object security changed\n”) ; 
break; 


case A_EVENT_DELETE_DIRECTORY 
printt (“Subdirectory deleted\n”}); 
break; 
default : 
printf(“Unknown event: %4Xh\n”, eventTypelD); 


Figure 15-3. Listing of 
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Suggested Enhancements 





AUDITVOL is only a reporting utility. A complete auditing solution 
must also configure auditing. AUDITVOL only deals with volume 
events. A complete audit utility should also configure and report on 
directory events. Novell’s solution is to have one monolithic utility that 
handles configuring and reporting. A better solution may be to have 
separate utilities for configuring and reporting. And as with most 
utilities we present in this book, AUDITVOL would benefit by being 
rewritten for Presentation Manager. 
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...let him choose 
Out of my files, his projects to accomplish. 


—William Shakespeare, Coriolanus 


NetWare file system access is transparent in OS/2. This means that if 
you are programming in C the standard library functions like open, 
fopen, fbrintf, etc. will open, read, write, and close files on the NetWare 
file system the same as if you were writing to alocal OS/2 HPFS or FAT 
file system. Consequently, any file IO programs you have already 
written for OS/2 should work unchanged. 


The purpose of this chapter, then, is to present some of the additional 


features and attributes files can have on a NetWare file server that are 
not available in either the FAT or HPFS files systems of OS/2. 
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The NetWare File Server 





In NetWare 2.x and 3.x, the file server was the highest level component 
of the NetWare file system. Indeed, a single file server with one or more 
connecting workstations constituted a local area network (LAN). 
However, in many LANs the need to share more data, to support more 
users, or to categorize the data being stored led to more file servers 
being introduced and connected into a network of LANs. For example, 
one server might be dedicated to storing accounting files, another to 
storing source code. Other servers might be dedicated to servicing 
print jobs or for receiving and routing EMAIL. Because of this prolifera- 
tion of servers workstations needed the ability to connect to more and 
more servers simultaneously. 


In NetWare 4.x, Novell introduced a higher level “network” component 
with NetWare Directory Services (NDS). “Logging onto the server” 
was superseded by “authenticating to the network.” With a “directory” 
of 4.x servers—also known as a “tree”—a user doesn’t need to maintain 
separate accounts on all the different servers he needed to access. 
Rather, rights and permissions are maintained in the “directory” of all 
the servers in the tree. 


Note: The use of the word “directory” gets confusing quickly 
in NetWare; we need to distinguish between the NetWare 
Directory Services directory, the file system directory, and 
the directory which is a hierarchal container within the 
logical directory structure. So here’s how we'll try to do it. 


When we refer to the NetWare Directory Services directory 
we'll identify it as the NDS directory. When we refer to the 
file system directory we will just use the word directory. 
When we want to refer to a logical container in the file 
system directory structure we'll call it a subdirectory. And 
when we want to refer to the residence of a parish priest we 
will use the word rectory. 


So even though the NDS directory now manages users and access to 
file servers, the files themselves are still stored on individual servers. 
The file server is still the highest component of a file with the NDS 
directory replacing the “bindery,” not the file system. File access rights 
are still stored on the file server, with the object ID from the local 
Directory Services replica being used to indicate what objects have 
access rights. 
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File Server Names 


File Server Versions 


As you interrogate or manipulate file attributes or characteristics, the 
two highest level pieces of information you will need are file server 
“name” and file server “version.” 


Specific API calls that return a file server’s name are discussed in the 
next chapter. For now just remember the file server name is sometimes 
required as part of a complete NetWare path and, of course, is neces- 
sary when specifying Universal Naming Convention (UNC) paths. (In 
NetWare UNC paths are described as paths specified in the following 
format: \DEVICE\VOL\DIR\DIR\DIR... .) 


There is, to be sure, a lot of ambiguity in the Client SDK reference 
manual about whether “full path” arguments require a server and vol- 
ume name at the front of the path string or just a volume name. 
However, most the APIs get the server information from the connection 
ID and don’t require a server name. Additionally, if you use a directory 
handle of 0, you will want to include a “VOL:PATH” parameter as the 
NetWare path. We hope that the sample code provided in the next 
chapter will help resolve some of the ambiguities found in the documen- 
tation, and a little trial and error should resolve the rest. 


Many of the file system related APIs will work on 2.x, 3.x, and 4.x 
versions of NetWare, and you will want to always be aware of the 
version number of the file server you are working with. Some API calls 
like NWGetVolumeStats are supported only on NetWare 2.x. Others, 
like NWGetExtendedVolumeInfo, work only on NetWare 4.x. So always 
keep an eye on the documentation to see what APIs work with which 
versions and, where appropriate, add version tests to your code before 
making certain calls. Making the wrong call to the wrong server won’t 
usually “crash” or “abend” the server, but the call will most likely fail in 
your program. 


Finally, in order to avoid the string manipulation overhead of handling 
server names in API calls, almost all of the APIs require you to pass ina 
connection handle (or conn) in each call. These connection handles 
resolve to a single file server. 
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File System 
Architecture 


Note: In the two file system chapters in this book, we will not 
address NetWare 2.x specific issues. Since NetWare 2.x is 
over five NetWare revisions old, we will instead focus on file 
system characteristics that are available on 3.x and 4.x file 
servers. 


NetWare Volumes 





The next level in the NetWare File System hierarchy is the volume. 
Volumes are usually the logical grouping of one or more physical disks. 
That is, if a file server has two 512 MB drives, it can be configured to 
have two 512 MB volumes or to have a single 1 GB volume. The file 
server can also divide either or both of the drives into several smaller 
volumes if desired. In fact, given the proper drivers, any readable 
media—CD-ROMs, magnetic tape, removable cartridges, diskettes, 
etc.—could be mounted as a NetWare volume. 


All NetWare volumes have a name and a number. But since numbers 
are more efficient to work with, most volume related APIs take the 
volume number as the parameter. However, if you have both a connec- 
tion handle (which identifies the specific server you are connected to) 
and the volume name you can call NWGetVolumeNumber to get the 
volume number from the file server’s volume table. 


Before getting into some of the other aspects of a NetWare volume, we 
need to quickly cover some basic file system architecture. The smallest 
units on a NetWare file system are 512 byte units called sectors. These 
sectors are in turn grouped together into larger units call blocks or 
clusters. The size of NetWare blocks are configurable on a per volume 
basis and can be set at eight-sector blocks (4K), 16-sector blocks, 32- 
sector blocks, 64-sector blocks, or 128-sector blocks (64K). When the 
NetWare operating system reads file information, it does so 2 blocks at 
a time. 
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File Allocation Table 
(FAT) 


Directory Entries 


The location of the first 
block of the file 1s contained 
in the Directory Table or 
Directory Entry Table for 
the volume. 


On one hand, configuring a file server volume to use 64K blocks greatly 
speeds up the time required to read large files. However, it also means 
that a small file—which may be only three bytes long-——will take up a 
full 64K block. On the other hand, configuring a file server to use 4K 
blocks, improves the space efficiency of the volume, but slows down the 
file system’s response time. 


Assuming we have a volume configured to use 4K blocks, a 16K file 
would be spread across four separate blocks, and these blocks may or 
may not be next to each other or contiguous on the disk. Consequently, 
the volume maintains a file on the volume that contains an index (or 
links) for identifying which blocks belong to which files. This index is 
called the File Allocation Table or FAT. Ifa block is in use by a file, its 
FAT entry will either contain a link to the next block belonging to the 
file or a-1 indicating that it is the last block of the file. But one piece of 
information that the FAT does not contain is the information about 
which block is the first block of the file. 


The location of the first block of the file is contained in the Directory 
Table or Directory Entry Table for the volume. The Directory Table is 
another file that contains—along with the starting block of the file— 
additional file information (name, attributes, etc.), hierarchal position 
references (parent subdirectory), and corresponding name space infor- 
mation. The bulk of this information is kept in three structures called 
nodes: the file node, the directory node (or subdirectory node to be 
consistent with our convention), and the trustee node (which is where 
access privileges are stored). 


At the directory table level subdirectories and files are handled in the 
same way. That is, a subdirectory has an entry in the directory table just 
like a file, and the same kind of information recorded in a file’s directory 
entry is recorded in a subdirectory’s directory entry. The biggest 
difference is that subdirectories have a subdirectory node and files do 
not. 
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Directory Handles The NetWare file system does not maintain a subdirectory structure, 
per se. Rather the subdirectory structure is the hierarchal relationship 
of files that can be determined by searching the directory table. Each 
directory entry has—in both its file node and subdirectory nod—a link 
to its parent subdirectory. And any files or subdirectories that have the 
same parent subdirectory are considered to be in the same sub- 
directory. 


In order to speed up directory table searches, a client workstation can 
allocate a directory handle (for a subdirectory) which is an index into 
the directory table identifying the location of that subdirectory’s direc- 
tory table entry. Some APIs let you identify paths using a directory 
handle, or a combination of directory handle and relative path from the 
directory handle. While not really part of the file system itself, directory 
handles provide an often used method for identifying a file 
or subdirectory’s location within the volume’s overall subdirectory 
structure. 


For each connection, the server maintains a table—a directory handle 
table—with entries for the paths a workstation maps on that server. 
These entries are called directory handles, and additional directory 
handles can be added by the client workstation as needed. (We suppose 
we should call them sub-directory handles, but since the API reference 
doesn’t refer to them this way, and since we aren’t aware of any other 
ambiguous uses of the term, we won’t.) A workstation can allocate up to 
254 directory handles on a server. 


For example, suppose you map your first drive to the root of volume 
SYS on file server PEQUOD. Ifyou allocated a directory handle named 
dirHandle for this drive, it would resolve to PEQUOD/SYS. Suppose 
later, you wanted to use APIs to access a subdirectory that is four levels 
down from the root in a subdirectory named USERS\AHAB\CODE\OS2. 
One way is pass the API a full NetWare path: 


PEQUOD/SYS:USERS\AHAB\CODE\O0S2 


Another way is to use the directory handle for PEQUOD/SYS and then 
add a relative path from that directory handle. You would pass the API 
two parameters: 


dirHandle + USERS\AHAB\CODE\O0S2 
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As a general rule, don’t use 
permanent directory 
handles. 


NetWare Name Spaces 


Adding Name Spaces 


Or, to eliminate the overhead of string manipulation altogether, you 
could allocate a new directory handle to the same place, name it 
newDirHandle, and then pass newDirHandle to the API. 


Finally, be aware that directory handles are either permanent or 
temporary. They are created using NWAllocTempDirHandle or 
NWAllocPermDirHandle. Temporary directory handles are all released 
when the application that created them terminates. Permanent direc- 
tory handles must be explicitly released using the 
NWFreePermDirHandle or they will continue to occupy a slot in the 
user’s directory handle table until the user logs out. As a general rule, 
don’t use permanent directory handles. 


The first file system that NetWare supported was DOS. But NetWare 
soon expanded its file system to handle non-DOS clients like OS/2 and 
Macintosh. This allowed these clients to open, close, read, and write 
files on a NetWare volume just as they would have on their native files 
system. This additional file system support was provided through 
NetWare Loadable Modules (NLMs) called name spaces. While file 
naming is the most obvious difference between file system formats, 
these name space NLMs also handled architectural differences like 
supporting the Macintosh resource fork. 


Let’s look at an example of how name spaces work. Suppose we wanted 
to allow OS/2 clients to take advantage of the long name support 
provided by HPFS. The server administrator would enter the following 
commands on the server console: 


:load os2.nam 
:add name space os2 to volume sys 


When the OS/2 name space is added to a volume, two things happen. 
First, the server takes every entry in the DOS directory table and 
duplicates it in an OS/2 directory table. This OS/2 directory table is 
often referred to as the OS/2 name space. The second thing that 
happens is anytime a file is created in the OS/2 name space, its direc- 
tory entry is duplicated in the DOS directory table. And vice versa. 
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Directory Handles and 
Name Spaces 


If the OS/2 name space ts 
loaded on the volume, all 
the directory handles your 
OS/2 program allocates 
will be, by default, in the 
OS/2 name space. 


Each directory entry is duplicated across all loaded name spaces. So if 
you have three name spaces loaded—DOS, OS/2, and Macintosh—the 
directory information for each file and subdirectory will be replicated 
three times in an operating specific fashion. The DOS directory entry is 
always at the head of the linked-list of replicated name space directory 
entries for a file. That is, with any other name space than DOS, the 
NetWare operating system will always locate the DOS version of the 
directory entry and then use the information in the DOS entry to find 
the other name space associated with it. 


Because of the replication of directory entries, don’t add a name space 
to a volume unless you have over 10MB of available disk space. 


Note: In NetWare 2.x the entire directory table for a volume 
was cached in memory when the server initialized, and the 
directory table was limited to 32,000 entries. In NetWare 3.x 
and 4.x, directory entries are cached as needed and are 
limited only by the space available on the volume. 


Both files and subdirectories have duplicate entries in each name space 
loaded on the volume. However, a directory handle can only point to 
one subdirectory in one name space. Consequently, it is important to 
keep track of which name space your directory handle has been allo- 
cated for. 


If you write an OS/2 program that allocates directory handles on a 
volume that does not have the OS/2 name space loaded, all your 
directory handles will, by default, be allocated in the DOS name space. 
However, if the OS/2 name space is loaded on the volume, all the 
directory handles your OS/2 program allocates will be, by default, in 
the OS/2 name space. 


When you write your program, keep in mind that the OS/2 name space 
may or may not be loaded on a server when your program executes and 
in turn your directory handles may or may not be in the OS/2 name 
space. You can use the NWAllocTempNSDirHandle2 call to get the 
equivalent directory handle in a different name space. 
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Salvageable Files 


Trustees 


When you delete a file in NetWare, the file itself is not removed from the 
volume. Rather, the directory entry for the file is moved to a separate 
allocation table which is used for keeping track of deleted files. In 
addition, any associated name space directory entries are also copied 
into this table along with some additional information about who de- 
leted the file. These files can be permanently removed from the volume 
using the “purge” related APIs or they can be restored back to the 
primary directory table using the “salvage” APIs. 





‘Subdirectories 


The next level in the NetWare File System hierarchy is the sub- 
directory. Actually, subdirectories look a lot like files, only they have a 
directory node structure (or subdirectory node structure) in their 
directory entry. And it is in this subdirectory node that directory 
attributes and user rights are recorded. 


When any user on a NetWare file server is granted rights of any kind to 
a subdirectory, he or she becomes a trustee for that subdirectory. And 
the level of access the user is given is called his or her assigned rights 
or assigned trustee rights. In addition, the user also obtains rights to 
any subdirectories that are logically below that subdirectory. Which 
means that if a user were to go into a subdirectory below the 
subdirectory where his trustee rights were assigned, he or she would 
not have any assigned rights, but rather would have inherited rights or 
inherited trustee rights. Of course, there are some exceptions. 


In NetWare 2.x all trustee assignments were granted at the subdirectory 
level. However, NetWare 3.x and 4.x also allow administrators to assign 
users rights to individual files and directories that are different than his 
or her inherited rights (the trustee rights of the parent subdirectory). 
That is, an administrator may grant you all rights to a subdirectory, 
except for one file for which he grants you only “read” rights. 
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Assigned rights, however, take precedence over inherited rights. Even 
if a user is granted all rights to a subdirectory, he will not be able to fully 
access any subdirectories or files for which he has been assigned fewer 
rights. The outcome of the file server’s comparing assigned rights and 
inherited rights is known as a user’s effective rights. 





We'll discuss the trustee rights available for directories later when we 
discuss the trustees rights available for files, since they’re the same. 


Directory Space Along with restricting user’s rights to a subdirectory, the NetWare 

Restrictions administrator can also generally restrict the space available to the 
directory. The administrator can also restrict how much total space a 
user ID can take up on a given server (NetWare 2.x and above) or a 
given volume (NetWare 3.x and 4.x). Consequently, it is a good idea 
before performing any extensive file copy or file creation functions to 
check if there is enough total disk space, check if there is enough disk 
space allocated to your user ID, and call 
NWGetDirectorySpaceRestrictions to check for any restrictions that may 
have been placed on the size of the subdirectory. 


The lowest level in the NetWare File System hierarchy is the files 
themselves. Again, files on a NetWare file server can be open, read, 
written, and closed using standard library functions just as they are on 
your local file system. However, on a NetWare file system, there can be 
additional file attributes and file access restrictions placed on files. 


File Attributes In OS/2 the FAT and HPFS file systems provide the following file 
attributes: 


Archive 
e Hidden 
e Read Only 


e System 
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NetWare file systems provide the following file attributes: 
Delete-Inhibit 

Rename-Inhibit 

Migrated 

Don’t Migrate 

Compressed 

Immediate Compress 

Don’t Compress 

Can’t Compress 

Copy-Inhibit 

Execute Only 

Immediate Purge 

Read-Write 

Shareable 

Some of these NetWare attributes are directly affected by the settings 
of FAT or HPFS attributes. For example, if you set a file on a NetWare 
file server to “Read Only,” the “Delete Inhibit” and “Rename Inhibit” 
attributes will also be set. 

In addition, NetWare 2.x uses the following file attributes: 
Transactional 

Indexed 

Read Audit 


Write Audit 
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Trustees 


File Synchronization 


As discussed above, file attribute settings have a direct effect on your 
ability to see and manipulate NetWare files in OS/2. In addition, your 
ability to see and manipulate files will also be affected by your access 
rights or trustee rights. Your rights to files and subdirectories can be 
set as follows: 


Supervisor Rights 

Read Rights 

Write Rights 

Create Subdirectory and File Rights 
Erase Subdirectory and File Rights 
Modify Directory and File Rights 
Scan for File and Directory Rights 
Change access control 


As a general rule, you will only be able to read the trustees rights that 
affect you; to set rights you will need to have “Create Subdirectory and 
File Rights” rights to a subdirectory or file (or have SUPERVISOR 
rights which by default give you all rights everywhere on the server). 
For example, in a given subdirectory, you could query the server to see 
if you have “Create Subdirectory and File Rights” in that subdirectory. 
If you do, then you could create a new subdirectory and grant “read” 
and “file scan” rights to another user. 


In multi-tasking operating systems like OS/2, and in multi-user file 
systems like NetWare, the opportunity exists for multiple users, mul- 
tiple programs, or multiple processes to access the same file simulta- 
neously. Consequently, some kind of “locking” or “semaphoring” sys- 
tem needs to be available to manage instances where simultaneous file 
writes might occur. 
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The best strategy for file 
synchronization 1s to use 
the APIs available to OS/2. 


The best strategy for file synchronization is to use the APIs available to 
OS/2. This makes your programs portable across different networking 
operating systems. For example, if you need to lock a file before 
performing an operation on it, you should open the file using the sopen 
call with “deny write” flags. Or you could call the OS/2 API 
DosSetFileLocks before opening the file. 


However, it is also possible to use NetWare file locking APIs to keep 
simultaneous file writes from interfering with each other. This can be 
accomplished through either file locks or record locks. “File locks” 
block access to the entire file, while “record locks” only restrict certain 
records or bytes ranges within a file. 


When locking records within a file, you can lock either physical records 
or logical records. The APIs that log and lock physical records take 
parameters that specify a specific range of bytes at a specific offset in 
the file. Physical record locks are specific to a particular file. 


But the APIs that log and lock logical records use a string parameter to 
“logically” identify a range of bytes to lock. Records are not actually 
locked; rather, the string is locked, and identically named strings are 
kept from interfering with each other. Consequently, if you are placing 
logical locks on files, all the other programs using these files need to 
understand and participate in the “logic” of the names. Logical record 
locks are specific to a particular server. 


Note: Never mix logical locks with physical locks. 


A final option that NetWare provides for synchronizing files are sema- 
phores. Semaphores do not actually lock files or records, rather they 
are flags that can be examined prior to attempting writes or updates to 
particular files. Indeed, semaphores may signify information that has 
nothing to do with files. Rather, all the programs or processes that may 
be using the semaphore participate in examining the semaphore and 
taking the action appropriate to the semaphore’s setting. 
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Sub-Allocation 


Migrated Files 


Compressed Files 


NetWare 4.x Features 





While a lot of attention was given to NetWare Directory Services 
in NetWare 4.x, there are a number of significant features that were 
added to the file system in NetWare 4.x that are, perhaps, equally as 
significant. 


Sub-allocation was introduced in NetWare 4.x to reconcile the size 
versus speed tradeoff with directory blocks. Remember, that if you 
configure a volume to use 64K blocks, even the smallest file will take up 
64K worth of space. With sub-allocation enabled, however, a 2K file only 
takes up 2K of space. The granularity is reduced from blocks to sectors: 
512 bytes now becomes the minimum unit a the server will read in ata 
time. You will probably never deal directly with the sub-allocation 
processes running on the NetWare server, but some sub-allocation 
information is available to the OS/2 client through the APIs. 


In order to conserve space on the file server, NetWare 4.x provides file 
migration that moves file to “off-line” storage like tape or writable 
optical drives. Migrated files still appear in directory listings in the 
same manner as “on-line” files. However, when the file is opened, there 
will inevitably be a delay in moving the file back “on-line” (de-migrating 
the file). 


Another space conservation service introduced in NetWare 4.x is file 
compression. Infrequently used files, or files specifically designated for 
compression, can be compressed. These files are still visible in direc- 
tory listings, but are not uncompressed until they are opened. 
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“To comprehend the whole of the others, you must take the 
volume down and read it.” 


—Walter Bagehot, Essay on John Milton 


The following chapter describes a program called FILEDUMP.EXE 
that displays more NetWare file system information about a sub- 
directory or file than most people care to know. Figure 17-1 describes 
the command line syntax for the program and the simplifying 
assumptions we’ve made in putting the program together. 
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Figure 17-1. 
Description and 
Simplifying 
Assumptions for 
FILEDUMP.EXE. 


PROGRAM: 


DESCRIPTION: 


SYNTAX: 


REMARKS: 


SIMPLIFYING 


ASSUMPTIONS: 


FILEDUMP.EXE 


Displays NetWare subdirectory and file 
information. 


FILEDUMP [fileName] 


If FILEDUMP is entered without a 
parameter, the current subdirectory 
1ATormation 1S displayed. If FILEDUMP is 
entered with a fileName parameter, then 
the current subdirectory information and 
the information about the specified file 
will be displayed. 


« All file names specified must be in the 
Current directory and the name and case 
of the name must be the same as it was 
originally entered. 


e We assume that the filename will be in 
DOS “8.3 Tormat. (However, the 
algorithm for shortening long OS/2 
names is provided in this chapter.) 


e On any error or unexpected return, the 
program terminates. 


« This program does not support 2.x 
servers. We don’t check the server 
version number for 2.x servers before 
making calls that do not support 2.x. 


« When calculating megabytes, we don’t do 
floating point division. We simply do 
integer division and approximate. 
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~ NWGetDriveStatus 


Getting a Connection Handle 





As in most NetWare programs, the first thing you need to do is geta 
connection handle. And, when dealing with file system oriented appli- 
cations, there are three very useful calls you can use to do this: 
NWGetDriveStatus, NWParsePath, and NWParseNetWarePath. 


NWGetDriveStatus is the call you will want to use when you don’t have 
any particular path information and just want a connection handle to the 
“default subdirectory.” We do this in FILEDUMP by calling 
NWGetDriveStatus with the parameter driveNumber set to 0 
(DEFAULTDRIVE). By “default subdirectory” or “default drive” we 
mean the subdirectory where the program was started from. (If this 
seems confusing it is probably because we ended that last sentence 
with a preposition.) To explain a little better, let’s look at an example of 
how NWGetDriveStatus works. 


Suppose drive G: were mapped to server PEQUOD, volume SYS, 
subdirectory USERS. Then suppose you were to change directory to 
subdirectory AHAB and type in the FILEDUMP command. At this 
point, your screen might look something like this: 


[G:\AHAB] x:\tools\filedump cetacean.txt 


When FILEDUMP executes and calls NWGetDriveStatus, the following 
information will be returned: 


conn—a connection handle to the server that contains the 
“default” subdirectory G\AHAB. In this case the connection 
handle would be to server PEQUOD. 


pathRootMapping—the path where drive G: was initially 
mapped. In OS/2 all drives map as root. In this example 
drive G: corresponds to PEQUOD/SYS:USERS. 


pathRelativeToRootMapping—the path from the root of 
drive. In this case it would be AHAB. 


fullPath—the full NetWare path including server name and 


volume name. In this case it would be PEQUOD/ 
SYS:USERS\AHAB 
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If you  aren’t concerned with jpathRootMapping or 
pathRelativeToRootMapping you can pass NULLs into the function. 


NWpParsePath This is the call you want use to get a connection handle for a specific 
drive letter or a drive letter and path. For example, if we were to pass a 
string defined as “H\USERS\STARBUCK” to NWParsePath, it would 
return the following information: 


serverName—the name of the server that drive H: is mapped to. 


conn—a connection handle to the server that drive H: is 
mapped to. 


volumeName—the name of the volume that drive H: is 
mapped to. 


dirPath—the path of the subdirectory relative to the volume. 
This means, that any path information between the root 
mapping for H:\and the volume name will be included. That 
is, if drive H: had been mapped to PEQUOD/SYS:MAIL then 
the string returned in  dirPath would be 
MAIL\USERS\‘STARBUCK. 


You can also use NWParsePath to parse the server and volume names 
off the path even without a file server connection. For example, even if I 
had no connections to file server DAGGOO I could pass the string 
DAGGOO/SYS:HARPOONEERS\MAIL to NWParsePath. The function 
would fail and return Ox880F, but it would return DAGGOO in 
serverName, SYS in volumeName, and HARPOONEERS\MAIL in the 
dirPath parameter. 





Note: NetWare APIs accept both forward and backward 
slashes as path delimiters. 


NWParseNetWarePath Most people try to use this call to get a directory handle for a 
subdirectory. Unfortunately, the behavior of this call can be erratic, so 


we suggest you don’t use it. Allocate directory handles yourself using 
NWaAllocTemporaryDirectoryHandle. But if you really want to use this 
call, we suggest you do extra error checking. For example, even if 
NWParseNetWarePath returns 0 (SUCCESSFUL) you should still check 
to see that it returned a dirHandle that is non-zero. 
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Assuming that a successful completion code implies a valid dirHandle 
can introduce a subtle bug in your program. This is because many calls 
that take a directory handle parameter will work correctly with a 
dirHandle value that is 0 so you'll think you have a dirHandle when you 
really don’t. You usually use zero for a dirHandle when you don’t know 
what it is yet—like when you call AllocTemporaryDirectoryHandle for 
the first time—or you don’t care what the dirHandle is because you’ve 
provided the API with a full path. 


Note: Allocating a directory handle is not the same thing as 
mapping a drive. Your program can allocate up-to-254 
directory handles on a server—and use them to create, open, 
and read files—without ever mapping a drive. As a general 
rule, you only need to map a drive to a server if you want to 
make NetWare file server directories available to programs 
other than your own. 


File Server Version Information 





Whenever you are querying or manipulating files and directories, you 
will always want to be aware of what version of file server the file and 
directories reside on. Depending on the file server version, you may 
have access to a wider range of information (as in 
NWGetExtendedVolumeInfo whose information structure is only avail- 
able on 4.x servers), you may have to access information in a slightly 
different way (as in NWAddTrustee which in 2.x does not allow you to 
grant file level trustee rights), or you may find parameters and fields 
have different meanings depending on the file server version (as in 
NWGetFileServerVersionInfo and NWGetFileServerInformation). 


As an example, let’s look at NWGetFileServerVersionInfo. In 
FILEDUMP.C, we call this function to get the file server version. (It 
returns the identical information as NWGetFileServerInformation, but 
when given the choice, we like to use functions that pass pointers to 
structures on the stack rather than 10 parameters.) There are three 
fields in the VERSION_INFO structure that contain different informa- 
tion depending on the file server version: 


e maximumServerConnections 


® connectionsInUse 
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e maxConnectionsEverUsed 


In the documentation, the remarks about these fields are non-existent, 
and the descriptions of these parameters in 
NWGetFileServerInformation are somewhat misleading. The best de- 
scription of these fields is in the NetWare NLM Library Reference under 
the GetServerInformation call. A summary of that information is pro- 
vided in Figure 17-2. If you look at the end of the sample code listing of 
PRNSRVR.C, you'll see an example of the kind of conditional branching 
you'll occasionally need to do when dealing with different file server 
versions. 


Parameter Pre-4.x Servers 4.x Servers 


maximumServiceConnections The maximum The current size of the 
connections supported connection table minus 
by the server. For a 250 one (i.e. one less than 
user version of 3.11, this the current number of 
value would be 250. workstation 
connections). 


connections/nUse The current number of The current number of 
connections currently authenticated 
attached to the server. connections to the 
Connections can be server. 
logged in or simply 
connected (not 
authenticated). 


maxConnectionsEverUsed The maximum number The maximum number 
of connections ever of connections ever 
simultaneously connected simultaneously 
to the server. Connections | authenticated to the 
can be logged in or simply —_| server. 
connected. 





Figure 17-2. A 
Description of the 
Parameters for 
NWGetFileServerInformation. 
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Volume Information 





Before you can get volume information for a server, you need to know 
either the volume name or volume number. In FILEDUMP.C, we get 
the volume name off the full NetWare path which we then use to call 
NWGetVolumeNumber. If you don’t have a volume name, you can get 
the name and number of all the volumes mounted on a server by 
repeatedly calling NWGetVolumeName. The pseudo-code in Figure 
17-3 illustrates how you would print the names of every volume loaded 
on the server. Of course, instead of printing the volume name you could 
build a table of volume names and their corresponding volume 
numbers. 


call NWGetFileServerVersionInfo to get the maximum 
number of volumes the server supports 


/* the first volume mounted on the server has a 
number of OQ */ 


set volumeNumber = 0 
LOOP through the maximum number of volumes supported 
call NWGetVolumeName using volumeNumber 
IF completion code = 0 
print volumeName 
ELSE call to NWGetVolumeName failed 
/* there are no more volumes mounted */ 
break 


increment volumeNumber 


Figure 17-3. Pseudo- 
code Example for 
Printing Names of all 
Volumes Loaded on 
Server. 


A NetWare File System Services Application 241 





Once we have the volume number we then call NWGetDirSpacelnfo. By 
passing in a 0 value for the directory handle we specify that we just want 
volume information for volume number’ volNumber. 
NWGetVolumelnfoWithNumber and NWGetVolumelnfoWithHandle re- 
turn essentially the same information, but, again, we prefer the 
economy of passing a pointer to a structure on the stack. (The same sort 
of information can be returned for a 2.x server by calling 
wai NwGetVolumeStats.) 
spacelnfo.availableBlocks When we print the volume information to the screen in the file 
and PRNDIRSP.C., we perform a relatively straightforward calculation to 
spacelnfo.purgeableBlocks convert the number of “blocks” of information that is returned into a 
more meaningful value of megabytes. The only “trick” here is to 
remember that the “real” number of available blocks are determined by 
adding spacelnfo.avatlableBlocks and spacelnfo.purgeableBlocks 
together. 


Extended Volume Information 


If you are connected to a 4.x server, there is additional volume informa- 
tion that is available to you from the © call 
NWGetExtendedVolumelnformation. However, while the NetWare 
Programmer’s Guide for C refers to this call, it is not documented in the 
function reference. Similarly, the functional equivalent of the 
programmer’s guide in the NLM SDK, Using NetWare Services for 
NLMs, also refers to a GetExtendedVolumelInformation call which is not 
documented either. Unfortunately, this limits the information available 
about the fields in the NWVolExtendedInfo structure defined in 
NWVOL.H. Figure 17-4, though, presents what little additional (and 
non-obvious) information we can provide. 


together. 
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Figure 17-4. 

Just a Bit More 
Information about 
Fields in the 
NWVolExtendedInfo 
Structure. 


Test this field with the four constants defined at the 
top of NWVOL.H: ViNetWare386, VINetWare286, 
VINetWare386v30, VINetWAre386v31. 









vollype 


numDataStreams 












Test this field with the five constants defined at the 
top of NWVOL.H: NWSubAllocEnableaBit, 
NWCompressionEnableaBit, NWMigrationEnabledBit, 
NWaAuditingEnabledBit, NWReadOnlyEnableaBit. 








Data streams essentially represent files. 
numDataStreams then is essentially the number of 
files on the volume. numCompressedDataStreams is 
essentially the number of compressed files on the 
volume. 








You can pass this value in to NWDSMapIDToName to 
get the name of the NDS object denoted by this ID 
and the connection handle. Remember, though, that 
you will also need to get an NDS context handle 
before making the NDS call. 


DirectoryServicesObjectlD 
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Unpacking Dates and 
Times 


Handling dates and times is not really subordinate to extended volume 
information, but we’re putting it here because it comes up at the end of 
PRNEXVOL.C. There are six functions in the SDK that manipulate 
dates: three that start with NWConvert and three that start with 
NWUnpack. While the programmer’s guide suggests you use the 
NWConvert calls, a comment in the NWMISC.H header file suggests 
that you use the NWUnpack calls. And for reasons of efficiency, we 
endorse the NWUnpack calls. 


If you are working with a parameter or field that has both “date” and 
“time” in its name, use NWUnpackDateTime to split the value. If you are 
working with just a “time” value or a “date” value, use NWUnpackTime 
or NWUnpackDate respectively to get the component hours, minutes, 
and seconds or years, months, and days. 


Of course, if you want to write your own date and time conversion 
strings, the byte format is documented in the NetWare Programmer's 
Guide for C under “File Date and Time Values” in Chapter 13, “File 
System Services.” 


Data Migration Information 





As the authors of this book, we understand that it is rather bad form to 
admit we don’t know much about these calls. However, we did not have 
access to the kind of equipment necessary to test sample code with data 
migration. But we do know that the call NWGetDataMigratorInfo does 
work, and Figure 17-5 shows a pseudo-code representation of how we 
handle the values it returns. However, we aren’t able to tell you how to 
get some of the more interesting information back—like estimated time 
to restore a migrated file—from a server with data migration enabled. 
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call NWGetDataMigratorInfo 
IF completion code is NOT 0 
IF completion code is Ox89FB 
the server does not support file migration 
ELSE 

the information returned by NWGetDataMigratorInfo is invalid 
ELSE 

the server supports data migration 

IF the DMPresentFlag is set 

data migration is currently active on the volume 
data migrator version numbers information is available 


number of modules supported information is available 


Figure 17-5. Pseudo- 
code Representation 
of How to Handle 
Return Values of 
NWGetDataMigratorInfo. 





Volume Name Space Information 





When you are working with the NetWare file system in OS/2, probably 
the single most important piece of information you need to know is 
whether or not the OS/2 name space is loaded on the volume you are 
working with. 
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The 0S/2 Name Space 
and Directory Handles 


The OS/2 Name Space 
and File and 
Subdirectory Names 


If the OS/2 name space is loaded, all of the directory handles your OS/ 
2 program allocate using NWAllocTemporaryDirectoryHandle will be in 
the OS/2 name space. This means you will have to use 
NWAllocTempNSDirHandle2 to allocate a directory handle in the DOS 
name space for any calls like NWScanDirEntryInfo that only operate in 
the DOS name space. 


If the OS/2 name space is not loaded, all of the directory handles your 
OS/2 program allocates will be in the DOS name space. 


When a file or subdirectory with a name greater than “8.3” is created in 
the OS/2 name space, a duplicate entry for the file or subdirectory is 
created in the DOS name space. However, in the DOS name space, the 
server truncates “long names.” This means that if you want to use the 
equivalent DOS name for the file or subdirectory on the server, you 
need to either get the DOS name from the server, or truncate the file 
name yourself the same way the server did. 


If the OS/2 name space is loaded on the volume, and you are working 
with a file that has a long name, you can get the “short” filename from 
the DOS name space using the NWGetNSEntryInfo call. In the call, you 
would set sourceNameSpace as NW_NS_OS2 and destNameSpace as 
NW_NS_DOS, and the entryInfo.entryName would come back with the 
DOS name of the file. 


Also remember that subdirectory names in OS/2 can be longer than 
“8.3,” so if you want to be certain you have the correct full DOS path you 
will need to allocate directory handles for every parent subdirectory 
back to the root of the volume and call NWGetNSEntrylnfo for each of 
these directory handles to get the DOS name for each one. 


You can also write your own routines to truncate file and subdirectory 
names. The algorithm in Figure 17-6 describes how the server shortens 
filenames. 
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/* handle the file name extension first */ 
Start at the far right of the long OS/2 file name 
WHILE character is NOT a period 


move left one character 


IF no periods exist in the long OS/2 file name 
there is no DOS extension 
ELSE 
/* there is a period in the long OS/2 file name */ 
IF the period is NOT the first character of the long OS/2 file name 


IF all characters between this period and first character 
of long OS/2 file name are periods 


there is no DOS extension 
ELSE 
the file has an extension that is up to 3 characters to the 
right of first period found 
ELSE 
/* the long OS/2 file name starts with a period */ 


there is no DOS extension 


first character of the long OS/2 file name is NOT a period 
Start at the far left of the long OS/2 file name 
ELSE 
/* long OS/2 file name starts with a period */ 


Start at the first character to the right of the period (that is 
not a period) 


Figure 17-6. 

NetWare Algorithm for 
Shortening Long OS/2 
File Names to “8.3” 
DOS Names. 
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IF there is a period within the first 8 characters 
the DOS name begins with all the characters up to the period 
ELSE 
/* file name is longer than eight characters */ 
the DOS name begins with the first 8 characters of the long OS/2 file name 


WHILE the DOS name matches an existing DOS name 
with an earlier time stamp 


IF DOS name is less than 8 characters long 
append a zero at the end of the DOS name 
check for an existing match with this new DOS name 
ELSE 
/* DOS name is 8 characters long */ 


IF 8th character of DOS name is not a number (i. a 
character between O and 9) 


overwrite 8th character with a 0 (this the character 0, not a NULL) 
check for an existing match with this new DOS name 
ELSE 
/* DOS name ends with a number (i.e. a character between 0 and 9) */ 
IF last character of DOS name is NOT a 9 


increment last character to next numerical character (e.g. “7” 
to “8”) 


check for an existing match with this new DOS name 
ELSE 
/* DOS name ends with a “9” */ 


. change 9 to 0 
Figure 17-6. 


NetWare Algorithm for 
Shortening Long OS/2 LOOP 
File Names to “8.3” 
DOS Names. IF ph aieae character of DOS name is NOT a number 
(Continued) | a character between 0 and 9) 
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make preceding character a 0 


break 
ELSE 


/* preceding character is a number */ 
IF preceding character is a 9 
move back yet another character and see if it is a number 
loop again 
ELSE 
increment preceding character 


break 


Figure 17-6. 

NetWare Algorithm for 
Shortening Long OS/2 
File Names to “8.3” 
DOS Names. 
(Continued) 


Directory Entry Information | 





Directory entry information for a file or subdirectory can be obtained by 
calling NWGetNSEntryInfo or NWScanDirEntrylnfo. 
NWScanNSEntrylnfo is an alternate way of getting name space informa- 
tion about a directory entry, but it returns the same NW_ENTRY_INFO 
structure as NWGetNSEntrylInfo. NWScanExtendInfo works the same 
as NWScanDirEntryInfo, but it returns some additional data and re- 
source fork information (for Macintosh). 


Scan Calls with O$/2 © When it comes to determining whether file or subdirectory names 
Name Space match, some NetWare file system services are case sensitive. This is 

usually only an issue when the OS/2, NFS, or MAC name spaces are 
loaded because the file server preserves mixed case file and 
subdirectory names within these name spaces. Names coming back 
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from “get” calls will have the same upper and lower case characters as 
they were originally created with. So while OS/2 considers a file named 
“MixedCaseFileName” to be the same as a file named 
“MIXEDCASEFILENAME,” some NetWare calls may not. 


Scan calls that operate in non-DOS name spaces are case sensitive. 
This is probably why calls like NWScanDirEntryInfo were limited to the 
DOS name space only—it reduces the complexity of matching algo- 
rithms and requires programmers to simply uppercase names before 
making the call. However, with a call like NWScanNSEntrylnjfo, it is 
much more challenging to ensure that the search pattern passed to the 
call is the correct case—especially if the search pattern is supplied by 
user input. 


For example, if a scan call fails or if you are unable to allocate a non- 
DOS directory handle for a file, it may be because the file doesn’t exist. 
It may also be that the file exists but that the filename or full path you 
were using did not match the case of the file server’s name or full path. 


Disk Space Restrictions 





On a NetWare server, available disk space can be limited by physical 
restrictions, directory restrictions, or user restrictions. 


Physical Disk Space It may be a bit too obvious to talk about physical restrictions, but we felt 
like reminding you to make the NWGetDirSpacelnfo call at the begin- 
ning of your programs to see how much space is left on the volume. 
Granted, any available space may disappear before you get around to 
writing information to the volume, but if the volume has already reached 
its physical capacity, there may not be any point in your program’s 
continuing. 


Directory Restrictions It is also possible that the file server supervisor has put restrictions on 
the subdirectory (or a parent of the subdirectory) you want to work on. 
To determine this information, use the NWGetDirSpaceLimitList call, a 
call that is in every respect a leading candidate for “Worst Documented 
Call in the SDK.” 
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User Disk Space 
Restrictions 


To figure out what the buffer returnBuff was supposed to look like, we 
referred to ReturnSpaceRestrictionsForDirectory in the NLM 
programmer’s reference, and found that returnBuff is an array of “an- 
swer” structures that look like this: 


typedef struct answerStruct 
{ 
BYTE subDirsDeep; 
LONG maximumAmount; 
LONG currentAmount; 
} ANSWERSTRUCT; 


We also checked the call “Get Directory Disk Space Restriction” in 
NetWare Client API for Assembly which told us that the first byte of 
returnBuff tells you how many “answer” structures are in the buffer. 
With this information, and the glowing satisfaction of having solved yet 
another NetWare riddle, we could define return Buff as follows: 


SrErueL 

{ 
BYTE numberofAnswerStructs; 
ANSWERSTRUCTL56]; 
Char paddingL/]; 

} PeETUrnBurt : 


After NWGetDirSpaceLimitList has returned successfully, you can look 
through returnBuff. If every maximumAmount field is OX7FFFFFFF, 
there are no directory restrictions. If one or more of the 
maximumAmount fields are not 0x7FFFFFFF, the available directory 
space is effectively limited to the smallest maximumAmount value. 
Subtracting the value of currentAmount in the first answer structure— 
the subdirectory that you allocated the dirHandle for will always be 
first—from the smallest maximumAmount value yields the directory 
disk space restrictions. In FILEDUMP, though, we only checked for 
directory restrictions in the first answer structure. 


Disk space restrictions can also be made at the user level. To determine 
what, if any, restrictions are assigned to a user make the 
NWGetObjectDiskRestrictions call. In order to do this though, you will 
need to perform the following steps beforehand: 
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1) get a connection handle (NWGetDriveStatus) 
2) get a connection number (NWGetConnectionNumber) 


3) get the name of the user who has the connection 
(NWGetConnectionInfo) 


4) get the object ID that corresponds to the user name (NWGetObjectID) 


NetWare Rights" 





In FILEDUMP we display all rights—inherited, trustee, effective, etc.— 
with a printRights function. This function tests all rights masks against 
the TR_ defines in NWDENTRY.H. The TA_ defines in 
NWNAMESPC.H and NWDIRECT.H are a subset of the TR_ defines, 
so for convenience we lumped them all together. 


We also collapsed redundant defines into one test. For example, 
TR_DELETE and TR_ERASE both equate to a value of 0x10. 
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‘I print at my own risk,” said the author. 


—Miguel de Cervantes, Don Quixote 





Printing in NetWare 


Unless you’re one of those odd ducks who read computer books from 
cover to cover, you probably turned to this chapter to learn how to send 
a file from an application to a network printer. We can see how you 
might have gotten that idea from the title of this chapter, but the 
preferred method of printing from an application is to use NetWare’s 
Queue Management System (QMS) functions. If you’ve got a minute 
before you turn to those chapters, you might want to read on just a bit 
further, where we explain the two approaches to printing in NetWare. 
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When you print from an application on a stand-alone PC, data goes from 
your application, to a virtual printer device (LPT) in the operating 
system, then through a physical serial or parallel port to the printer. 
Many older applications, particularly DOS applications, are written to 
send data to one of three printer (LPT) devices in the operating system. 
NetWare maintains compatibility with older applications and operating 
systems by “capturing” data that is being sent to an LPT device, and 
redirecting it across the network to a file. NetWare puts the file into a 
applications and operating print queue, which is controlled by NetWare’s Queue Management 
systems by “capturing” data System (QMS). A print server then sends the data in the file to a printer 
that is being sent toan LPT nthe network, which may be attached to a workstation, a file server, or 
cabled directly to the network. For more information on printing in 
NetWare, see the Print Services manual in the NetWare manual set. 


NetWare maintains 
compatibility with older 


device, and redirecting it 


across the network to a file. 


This chapter covers the functions that manage print data capture. 


More and more programs are taking a second approach to NetWare 
printing. These applications bypass the LPT port and submit data 
directly to the NetWare print queue. The advantage to the application is 
that the user can select the destination for printed data after the applica- 
tion is running. When using print capture, the user must choose a 
printer and set up the capture before running an application. The 
functions that provide this capability are discussed in the Queue Man- 
agement System (QMS) Services chapters. 


Capturing a printer port affects all applications that use the port. In 
OS/2 sessions, capturing a port redirects print data for that port in all 
OS/2 sessions. Capturing a port in a global DOS or Windows session 


affects that port in all global DOS or Windows sessions. In a private 
DOS or Windows session, capturing a port affects only that session. 


Capturing Print Jobs 


There are four steps to completing a print capture: 
1. Capture the LPT port. 
2. Configure the capture (optional step). 


3. Send data to the port. 


254 OS/2 and NetWare Programming: Using the NetWare Client API for C 





Capturing the LPT Port 


Configuring Print 
Captures 


. “Flush” and end the capture, or cancel the capture and discard captured 


data. In the NetWare context, flushing means to close the capture file 
and have NetWare place it in a print queue. 


In DOS and Windows environments, print captures can be configured 
to be flushed automatically when the client workstation ends the cap- 
ture or after a specified time passes after data has been sent to the 
capture file. In OS/2, you flush the capture by closing the print device, 
or by calling NWFlushCapture. 


NWStartQueueCapture redirects an LPT port to a print queue. The 
function requires a connection handle to the server, an LPT device 
number, and either the queue ID or the queue’s name. The current 
version of the NetWare OS/2 Requester supports 9 LPT devices. 


There are a number of flags and parameters that control how captured 
data should be printed, plus a set of flags that can be read to get the 
status of a capture. 


Banner User Name 


The banner user name is a string that will be printed on the banner 
page, if the capture is configured to print a banner page. The banner 
user name is usually the user name of the user who has captured the 
port. The same banner user name applies to all LPT ports, but you 
control whether each LPT will print a banner page. 


Printer Strings 


NWSetPrinterStrings allows you to set two strings that control a cap- 
tured printer. The printer setup string is sent to the printer at the start 
of each printjob. The printer reset string is sent to the printer at the end 
of each print job. These strings can be used to set a printer into a 
particular print mode, then reset the printer to its default mode when a 
print job is complete. For example, an application could use the setup 
string to set the printer to print in landscape mode, then use the reset 
string to set the printer back to portrait mode printing. 
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Capture Flags 


Each LPT device has two data structures, called the capture flags, 
associated with it. The first set of flags can be set to configure how the 
LPT port handles print jobs sent to it. The second set of flags can only 
be read to obtain information about the capture. Use 
NWGetCaptureFlags to get the values of both sets of flags, and 
NWSetCaptureFlags to set the first set of flags. Figure 18-1 describes 
the first set of capture flags. 


jobDescription BYTE[50] 

jobControlFlags NWFLAGS Used internally by the requester. Should 
be set to 0. 

tabSize NWTAB Number of spaces tabs are expanded to. 
Range 1-18, default 8. 

numCopies NWNUMBER Number of copies of the captured file to 
print. Range 0 to 65536, default 1. 

printFlags NWPRINT_FLAGS See Figure 8-4. 


maxLines NWNUMBER Maximum number of text lines to print 
per page. 

maxChars Maximum number of characters to print 
per line. 


- 


reserved BYTEL9] 















String that appears in the print job’s 
description field in PCONSOLE and on 
the banner page. 


















Name of the form that must be mounted 
on the printer before the captured file 
can be printed. If the correct form is not 
mounted, the print server console 
operator will be notified to mount the 
form. 


Figure 18-1. Reserved. 
Fields of the 
NWCAPTURE_FLAGS1 


Structure. 
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formType NWFORM_TYPE 
half of the banner page. Must be null- 


bannerText BYTE[13] 
terminated. 


flushCapture- NWTIME Time to wait after the last data 
TimeOut is sent to the printer before flushing the 
capture. Ignored in 0S/2. 








Type of form that must be mounted on 
the printer before the captured file can 
be printed. If the correct form is not 
mounted, the print server console 
operator will be notified to mount the 
form. Range 0-255, default 0. 













String that will be printed on the bottom 

























NWFLAGS 









Flag indicating whether to flush 
the capture when capture is ended. 
Ignored in 0S/2. 


flushCapture- 
OnClose 





Figure 18-1. 

Fields of the 
NWCAPTURE_FLAGS1 
Structure. 
(Continued) 






Figure 18-2 describes the second set of capture flags. These flags can 
not be modified. Use NWGetCaptureFlags to get the values of both sets 
of flags. 
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NWCONN HANDLE 


NWLENGTH 


NWLENGTH 
LPTCaptureFlag NWFLAGS 
fileCaptureFlag NWFLAGS 
timingOutFlag NWFLAGS 
7 


NWFLAGS 


NWFLAGS 


setupString- 
MaxLen 






resetString- 
MaxLen 








printQueveFlag 








printJobValid 







Figure 18-2. 

Fields of the 
NWCAPTURE_FLAGS2 
Structure. 





Description 


Connection ID of the server containing 
the queue to which the captured data is 
directed. 


Object ID of the queue on the server to 
which the captured data is directed. 


Maximum length of the setup 
string. Set in the workstation’s 
NET.CFG file (PRINT HEADER =). 


Maximum length of the reset 
string. Set in the workstation’s 
NET.CFG file (PRINT TAIL =). 


DOS/Windows only. Set to OxFF when 
the port is captured, 0 otherwise. 


DOS/Windows only. Set to OxFF when 
capturing fo a file, 0 otherwise. 


DOS/Windows only. Set to OxFF when 
flush timeout count is being 
decremented, 0 otherwise. 


DOS/Windows only. Set to OxFF if 
data has been sent to the port, but the 
capture has not yet been flushed, 0 
otherwise. 


DOS/Windows only. Set to OxFF if 
QMS has assigned a job number to the 
print job, 0 otherwise. 


DOS/Windows only. Set to OxFF if 
QMS has opened a capture file for the 
job, 0 otherwise. 
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Figure 18-3. 

Bit Definitions of the 
printFlags Field of 
CAPTURE_FLAGS1. 


Sending Data to the 
Printer 


Canceling, Flushing, or 
Ending a Capture 





Figure 18-3 describes the bit definitions of the printFlags field of the 
NWCAPTURE_FLAGSI1 structure. 


The print job is released for printing if the submitting workstation loses 
its connection to the file server. 





Suppress form feed after job is printed. 
Print service will interpret printing control settings (tab size, etc.). 
0x80 Print a banner page. 





After you have captured an LPT port and configured its capture flags as 
desired, you use standard OS/2 functions to open the LPT device, send 
data to the device, then close the device. NetWare flushes the captured 
data when your application closes the device. 


Closing an LPT device implicitly calls NWFlushCapture, which closes 
the capture file and releases it to QMS for printing. Your application can 
also send a print job without closing the LPT device by explicitly calling 
NWFlushCapture. To end a capture, call NWEndCapture. Ending a 
capture before closing the LPT device causes the captured data to be 
discarded, rather than sent to the printer. To cancel a print job without 
ending a capture, call NWCancelCapture. 
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Print Services Example: PRINTCAP.C 





PRINTCAP.EXE is a text interface to the print capture APIs. The 
program displays a menu of each of the 13 Print Services APIs that can 
be called from OS/2. When you select one of the functions from the 
menu, the program gets any required input, calls the function, then 
displays any data returned by the function. If there is any error, 
PRINTCAP displays the value of the error code returned and dies 
unceremoniously. Figure 18-4 gives a description and simplifying as- 
sumptions for the program. 


PROGRAM: 


DESCRIPTION: 


SYNTAX: 


REMARKS: 


SIMPLIFYING 


ASSUMPTIONS: 


Figure 18-4. 
Description and 
Simplifying 
Assumptions for 
PRINTCAP.EXE. 


PRINTCAP.EXE 

Call print capture functions. 

PRINTCAP 

Just displays a menu, gets input’ for 


parameters, and calls the print capture 
functions. 


« One-to-one correspondence of menu items 
and print capture functions. 


« Does little or no verification of input 
values. 


« Dies ungracefully on any error. 
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Take this job and shove it. 


—Johnny Paycheck 





Queue Management System 


NetWare’s Queue Management System (QMS) is a general-purpose 
queuing mechanism that can serve as the foundation for client/server 
applications. NetWare uses QMS to manage the submission and queu- 
ing of print jobs. We describe the process for submitting data directly 
to a NetWare print queue at the end of this chapter. However, printing 
in not the only thing QMS is good for. Applications that use QMS have 
the following characteristics in common: 


Client/server architecture: The application can be split into two dis- 


crete pieces—a client that submits jobs, and a server that performs the 
action specified by the job. 
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e FIFO service order: Jobs are normally serviced in order of submission, 
although QMS does allow you to specify ajob type, which can be used to 
implement job priority. 


e One-way communication: Communication between the client and 
server is encapsulated in one file and a data structure that contains 
fields that tell the server how the job is to be serviced. The client 
creates the job file and fills in fields in the job structure before submitting 
the job. No mechanism is provided for the server to communicate with 
the client. The server cannot even assume that the client is still logged 
in when the job is serviced. 


e Value of service outweighs overhead: QMS’s operation depends on 
both network communication and file access, so efficient use of QMS 
Sending print jobs toa Yequires that the value of the server’s services outweigh the overhead 
of submitting the job. For example, NetWare printing requires you to 
transmit the data to be printed, over the network to the file server, 
where it is either sent to a printer or transmitted again to a remote print 
up or slowed down while server, and then to a printer. The inefficiency of transmitting and 
printing, and users on storing the data to be printed is outweighed by the cost savings realized 
those workstations can by not having to attach a printer to every workstation. In addition, 
work more efficiently, Sending print jobs to a queue means that workstations are not tied up or 
slowed down while printing, and users on those workstations can work 

more efficiently. 


queue means that 
workstations are not tied 


e Relatively infrequent job submission: A queue can only hold 250 jobs 
simultaneously. The server must be able to service jobs quickly enough 
that no more than 250 jobs are enqueued while a job is being serviced. 


The one-way communication between client and server is the main 
limitation on how QMS can be used. QMS makes few assumptions 
about the type of services provided by a queue server. Using QMS, you 
can configure your applications to be one-to-one applications (one cli- 
ent, one server), one-to-many, many-to-one, or many-to-many. The job 
server presented in the following chapter, for example, is designed to 
have many users submit jobs to a single job server. When the load on 
the job server becomes too great, it could easily be reconfigured to have 
many job servers servicing a single queue (to which many users submit 
print jobs). A one-to-many configuration allows you to have many 
servers complete massive computations that can be broken in to 
smaller, discrete tasks. 
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Queue Objects 





QMS is implemented using bindery or directory objects. If you are 
implementing a new QMS-based application, you should take extra care 
to assure that the application works with both Directory services (NDS) 
and bindery-based clients. A QMS application written for NetWare 3 
will run on a NetWare 4 network, but only under bindery emulation. If 
a bindery context is not set at the file server, QMS functions return 
Ox89FC, NO_SUCH_OBJECT. 


A queue is defined by a queue object. As mentioned in the “Bindery 
Services Theory” chapter, queue objects have four properties: 
Q DIRECTORY, Q_OPERATOR, Q_SERVERS, and Q_USERS. 


Q_ DIRECTORY 


The Q_DIRECTORY property is a item property that contains the path 
of the queue directory, including the volume name. Queue directories 
can be placed anywhere on the file server, but are typically kept in the 
SYS:SYSTEM directory, where only the SUPERVISOR has access to 
them. The queue directory name is the object ID of the queue object. 


Q_OPERATOR 


The Q_OPERATOR property is a set property that has the object IDs of 
all objects that are authorized to be queue operators. Queue operators 
can delete any job from the queue, change the order in which jobs will 
be serviced, or place a hold on a job, preventing it from being serviced 
until the hold is removed. 


Q_ SERVERS 


The Q_SERVERS property is a set property that contains the object IDs 
of all objects that can service jobs in the queue. 


Q_USERS 


The Q_USERS property is a set property that contains the object IDs of 
all objects that can submit jobs to the queue. Users can delete their own 
jobs after they have been submitted, or place a hold on their own jobs. 
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Creating a Queue 





The QMS function NWCreateQueue creates a new queue object. The 
directory path in which the queue directory is to be created must exist, 
and must be passed as a parameter to the function. Only the SUPERVI- 
SOR or equivalent can create a queue. 

Applications that use QMS typically have an installation program that 
creates the queue object and directory, creates queue server objects, 
installs the applications that submit queue jobs and service them, and 
designates queue operators, users, and servers. 

A full-functioned QMS-based application will also have an administra- 
tion program (or the installation program will have administration 
functions) that enables the SUPERVISOR to: 

Add and delete queue operators 

Add and delete queue servers 

and enables queue operators to 

Add and delete queue users 

Delete jobs from the queue 

Place holds on and remove holds from jobs 

and enables users to 


Delete their own jobs from the queue 


Place holds on and remove holds from their own jobs. 





Submitting a Job 


Any user in the queue’s Q_USERS property can submit a job to the 
queue. To submit a job, the client application must: 


Create the job structure and job file by calling NWCreateQueueFile2. 
Figure 19-1 shows the job structure. 
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Figure 19-1. Queue 
Job Structure. 


typedef struct 


{ 


NWSTATION_NUM 


clientStation; 


NWTASK_NUM clientTask; 

NWOBJ_ID clientID; 

NWOBJ_ID targetServerlID; 

BYTE targetExecutionlimeL6]; 

BYTE jobEntryTime[6]; 

NWNUMBER jobNumber; 

NWJOB_TYPE joblType; 

NWJOB_ POSITION jobPosition; 

NWFLAGS JooControlFlags: 

BYTE jobFileName[14]; 

BYTE jobFileHandle[6]; 

NWSTATION_NUM servicingServerStation; 

NWTASK_NUM servicingServerlask; 

NWOBJ_ID ServicingServerIDNumber; 

BYTE jobDescriptionL50]; 

BYTE clientRecordAreal152]; 
} NWQueueJobStruct; 


e Assign values to the fields of the job structure. 
e Write the data associated with the job to the job file. 
e Submit the job for service by calling NWSubmitJob. 


Figure 19-2 gives a description of each field in the structure and tells 
when values are assigned to each field. 


If the job service protocol used by the client and server requires just a 
small amount of data to be transmitted (202 bytes or less), the data can 
be transmitted in the jobDescription and clientRecordArea fields of the 
job structure, and the job file can be left empty. 
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Figure 19-2. Job 
Structure Fields. 










Description When Set and 
by Whom 








clientStation Server's connection QMS sets when job 
number for the client structure is created. 


that submitted the job. 











clientTask Application number QMS sets when job 
of the client application structure is created. 
that created the job. 


clientID Object ID of the object QMS sets when job 
submitting the job. structure is created. 


targetServerID Object ID number of Client application sets 
the queve server that before submitting the 
is to service the job. job, and can change after 
A value of -1 submission (but before a 
(OxFFFFFFFF) server accepts the job for 
means that any server service). 
can service the job. 















































Client application sets 
before submitting the 
job, and can change 
after submission (but 
before a server accepts 
the job for service). 


The earliest time the 
job can be serviced. 
A value of 
OxFFFFFFFFFFFF 
means the job is to 
be serviced as soon 
as possible. 


The time that the job 
was placed in the 
queue. 


jobNumber A number that QMS sets when job 
identified the job. structure is created. 


jobType The client application Client application sets 
assigns a value to this before submitting the 
field to tell the queue job, and can change after 
server what type of job submission (but before a 
it is. Can be any value server accepts the job for 
except -1. service). 


QMS sets when job 
structure is created, and 
job to be serviced is maintains as jobs move 
at position 1. up in the queve. 


See Figure 19-3. See Figure 19-3. 


targetExecutionTime 
























QMS sets when job 
structure is created. 


jobEntryTime 

























Position of the job 
in the queue. Next 


jobPosition 








jobControlFlags 
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Figure 19-2. Job 
Structure Fields. 
(Continued) 


jobFileName 


jobFileHandle 


servicingServer- 
Station 


servicingServerlask 


servicingServer!D- 
Number 


jobDescription 


clientRecordArea 


Description 


Name of the job file. 
structure is created. 


Handle of the job file. 
Passed to functions 
that require a file 
handle (like write). 


File server connection 
number of the server 
that has accepted the 
job for service. 


Task number of the 
queue server appli- 
cation that has 
accepted the job for 
service. 


Object ID of the queue 
server that has 
accepted the job for 
service. 


Contains any data the 


client wants to commun- 


icate to the server. 
Typically contains a 
string (to be displayed 
by a queue manage- 
ment utility) that the 
describes the job. 


Contains any data the 
client wants to com- 
municate to the server. 
Typically contains 
parameters of how the 
job is to be serviced 
(see “Printing with 
QMS” at the end of this 


chapter for an example. 
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When Set and 
by Whom 


QMS sets when job 


QMS sets when job 
structure is created. 


QMS sets when a server 
accepts the job for 
service. 


QMS sets when a server 
accepts the job for 
service. 


QMS sets when a 
server accepts the job 
for service. 


Client application sets 
before submitting the 
job, and can change after 
submission (but before a 
server accepts the job for 
service). 


Client application sets 
before submitting the 
job, and can change after 
submission (but before a 
server accepts the job for 
service). 











Figure 19-3 shows the bit assignments of the jobControlFlags byte. 
Figure 19-4 gives a description of each flag and tells who sets each flag 
and when. 


Bit 7 6 5 4 3 2 1 0 
QF_AUTO_START 
QF_ENTRY_RESTART 
QF_ENTRY_OPEN 


QF_USER_HOLD 


QF_OPERATOR_HOLD 


Figure 19-3. Bit 
Definitions of the 
jobControlFlags Byte. 
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Figure 19-4. Job 
Control Flags. 





Flag Name Description When Set and 
by Whom 


QF _AUTO_START Determines what The client application 
happens fo the job sets this bit by calling 
if the client connec- NWChangeQueue- 
tion is broken be- JobEntry2 after 
fore the client sub- creating the job, but 
mits the job for before submitting it for 
service. If set, the service. 
job will be released 
for service. If cleared, 
the job will be removed 
from the queue. 


QF_ENTRY_RESTART Set if the job is to The client application 


remain in the queue can set this bit before 
if the queue server submitting the job, and 
QF ENTRY_OPEN 
QF USER_HOLD 


fails after accepting can change it after 
QF OPERATOR HOLD 






































the job for service. submission (but before 
a server accepts the job 
for service). 





Set when the client QMS sets this bit when 
has not yet submitted the client creates the 
the job for service (the job; clears it when the 
job is being added to client submits the job 
the queue). for service. 































Can be set by the client 
submitting the job, and 
the setting can be 
changed after 
submission (but before 
a server accepts the job 
for service). 


Set when the client 

has placed a hold on 
the job. The job will 
advance in the queue, 
but will not be serviced 
until the client clears 


the hold. 















Can be set by the client 
submitting the job, or 
by any queue operator 
at any time after the 
client creates the job. 


Set when a queue 
operator has placed 

a hold on the job. The 
job will advance in the 
queue, but will not be 
serviced until an 
operator clears the 


hold. 
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To prevent potential 
security breaches (ltke a 
user attempting to print a 
file he does not have rights 
to read), QMS allows 
queue servers to assume the 
access rights of the client 
that submitted the job being 
serviced. 


Client/Server Rights 


Servicing A Job 


The queue server application must be logged in to the server as the 
queue server object. The user running the program can log in as the 
object before running the server application, or the application can 
perform the login after it starts running (prompting the user for the 
queue server object’s password, if necessary). 


Before a server can service jobs in a queue, it must be in the queue 
object’s Q SERVERS property, and must attach to the queue by calling 
NWAttachQueueServerToQueue. To getajob to service, the server then 
calls NWServiceQueueJob2. The queue server can request a job of a 
certain type, or pass -1 in the jobType parameter to request the next job 
of any type. If there is a job in the queue that meets the following 
criteria, QMS will assign it to the server for service: 


The job’s jobType must match the type requested by the server, or the 
server must have requested jobType -1. 


The job’s targetServerID must match the job server, or be set to -1L. 


The job’s targetExecutionTime must have passed, or have been set to 
OxFFFFFFFF. 


The QF_OPERATOR_HOLD, QF_USER_HOLD, and QF_ENTRY_ 
OPEN flags must all be clear. 


The servicingServerIDNumber must be 0, indicating that the job is not 
being serviced by another server. 


NWServiceQueueJob2 returns the jobStructure and a handle to the job 
file that the client submitted for service. The file handle can be passed 
to the standard C runtime library vead function (in IO.H) to read from 
the job file. 


Because the queue server application is logged into the file server as 
the queue server object, it has different trustee rights to files and 
directories on the file server than the clients who submits jobs. To 
prevent potential security breaches (like a user attempting to print a file 
he does not have rights to read), QMS allows queue servers to assume 
the access rights of the client that submitted the job being serviced. 
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Aborting A Job 


This is done by calling NWChangeToClientRights2. If the server needs 
access to a file that the client may not have rights to, it can open the file 
before calling the function. When the server is done servicing the job, 
it calls NWRestoreQueueServerRights to have its access rights restored. 


When the queue server is done servicing a job, it signals to QMS that it 
is done by calling NWFinishServicingQueueJob2. QMS can then re- 
move the job from the queue and delete the job file. 


If, after accepting a job for service, a queue server determines that it is 
unable to service the job, it calls NWAbortServicingQueueJob2. QMS 
then handles the job in the manner specified by the QF_ENTRY_ 
RESTART flag setting. Ifthe flag is set, the job will be left in the queue 
to be reserviced. If the flag is cleared, the job will be deleted from the 
queue. The queue server must assure that it does not repeatedly try to 
service the same job. 


Managing Jobs | 


As mentioned earlier in this chapter, users can place holds on their own 
jobs, and queue operators can place holds on any job in the queue. The 
NWChangeQueueJobEntry2 function allows users and operators to 
change jobControlFlags settings to place or clear holds on jobs. Other 
fields in the job structure that users and queue operators can change to 
affect how jobs are serviced are: 

targetServerID 

targetExecutionTime 

jobType 

jobControlFlags 

jobDescription 
clientRecordArea 
To read the current setting of job structure fields, call 


NWReadQueueJobEntry2. 
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Queue operators and the client that submitted the job can delete a job 
by calling NWRemoveJobFromQueue2. Any queue user can get a list of 
jobs in the queue by calling NWGetQueueJobList2. Queue operators can 
then change the order of jobs in the queue by calling 
NWChangeQueueJobPosition2. 


Queue operators can also set flags in the queue status byte to control 
access to the entire queue. The queue status byte has three flags, as 
described in Figure 19-5. 


on 


=) QS CANT ADD JOBS If set, no new jobs can be submitted to the 
queue. 


QS SERVERS CANT ATTACH If set, no new servers can attach to the 
queue. 


QS CANT SERVICE JOBS If set, servers cannot service jobs in the 


Figure 19-5. Queue queue. 
Status Byte Fields. 





To read the queue status byte, call NWReadQueueCurrentStatus2,; to 
change flags in the byte, call NWSetQueueCurrentStatus2. 
NWReadQueueCurrentStatus2 also returns the number of jobs in the 
queue, the number of servers attached to the queue, and the object IDs 
and connection numbers of attached servers. 


QMS also has a 64-byte record for each queue server attached to the 
queue. Queue users or operators can get the contents of the queue 
status record by calling NWReadQueueCurrentStatus2. Queue servers 
can use this area to communicate any type of status information to 
queue users and operators. Novell recommends that the first four bytes 
of the record contain the number of arbitrary accounting units that will 
be charged to the user’s account for servicing a typical job (if account- 
ing is enabled on the file server). 
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Figure 19-6. Queue 
Job Functions. 


Figure 19-7. Queue 
Job Management 
Functions. 








QMS Functions 


QMS functions can be separated into four groups: queue job functions, 
queue job management functions, queue management functions, and 
queue server functions. The four groups are summarized in the Fig- 
ures 19-6 through 19-9. 






NWCloseFileAndAbortQueueJob2 Deletes a queue job after it has been created, 
but before it is submitted to the queue. 


NWCloseFileAndStartQueveJob2 Submit a queue job for service. 








NWCreateQueveFile2 





Create a queue job and job file, and get a 


handle for the job file. 


NWChangeQueveJobEntry2 
NWChangeQueuveJobPosition2 
NWGetQueveJobFileSize2 
NWReadQueuveJobEntry2 
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Figure 19-8. Queue 


Figure 19-9. Queue 
Server Functions. 











NWCreateQueve Creates a queue object and its properties. 


NWDestroyQueue Deletes a queue object from the bindery or 
directory. 


NWGetPrinterQuevelD Returns the object ID of the queue mapped fo a 
user's LPT port (actually a print function, but 
Novell documentation groups it with QMS 
functions). 


NWReadQueveCurrentStatus2 Reads the queue status byte for a queue. 
NWSetQueveCurrentStatus2 Sets the queue status byte for a queue. 


fon in 

NWAbortServicingQueveJob2 Abort servicing a job after the server has 
accepted it for service. 

NWAttachQueueServerToQueue Attach the application to a queue, so that it 
can service jobs in the queue. 


NWChangeToClientRights 



























Allows a queue server to assume the access 
rights of the client that submitted the job 
being serviced. 





Detach a queue server from a queue, so it 
can no longer service jobs in the queue. 


NWDetachQueveServerFromQueue 








NWFinishServicingQueveJob2 Signal to QMS that the server is done 
servicing a job, so it can be removed from 


the queue. 











NWReadQueveServerCurrentStatus2 Reads the server status record for a queue 


server. 
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Figure 19-9. 
Queue Server 
Functions. 
(Continued) 


NetWare uses the client 
record area to 
communicate print job 
configuration data beyond 
what is contained in the 
other fields of the job 
structure. 


NWRestoreQueueServerRights Restores a queue server's access rights after 
assuming a client’s rights while servicing a job. 


NWServiceQueveJob2 Get a queue job and its associated file for 
service. 


NWSetQueveServerCurrentStatus Sets the server status record for a queue 
server. 








Printing with QMS | 


Although we discuss the basic algorithm for submitting a job to a QMS- 
managed queue in the next chapter, we'll give you a sneak peek at it 
here in the context of sending data to a network printer. The two 
differences between the process for submitting a print job to a print 
queue and another type of job to another type of queue is (1) the type of 
queue object you search for in the bindery or directory, and (2) the 
application-specific data that goes in the clientRecordArea field of the 
job structure. NetWare uses the client record area to communicate 
print job configuration data beyond what is contained in the other fields 
of the job structure. 


Figure 19-10 gives pseudo-code for sending a print job to a QMS print 
queue. 
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IF you have a bindery connection 















Attach to the file server you want to search for print 
queues. 

Get the connection handle of the file server to use in 
Subsequent NetWare calls. 

Use NWScanObject to scan for all objects of type 

OT _PRINT_QUEUE. 


ELSE IF you have a Directory services connection 


Get the context you want to search for print queues 
scan for print queue objects (see the NetWare 
Directory Services Sample Application Chapter for the 
algorithm. 


Select (or let the application user select) which 
print queue to send the data to. 

Get the object ID of the print queue object. 
Configure print job options by setting fields in a 
Structure of type NWQueueJobStruct, including the 
clientRecordArea (see Figure 19-11). 

Call NWCreateQueueFfile2to create a queue job and get 
the handle of the associated file. 

Write the data to be printed in the job file. 

Call NWCloseFileAndStartQueueJob2to send the queued 


Figure 19-10. | file to the printer. 


Pseudo-code for 
Sending a Print Job to 
a QMS Print Queue. 


Figure 19-11 describes the fields in the client record area of a print job’s 
job structure. The fields are basically the same as the fields of a captured 
LPT port’s NWCAPTURE_FLAGS1 structure (see the Print Services 
Theory and Application chapter). Using the client record area in this 
way allows applications to control printer operations when using QMS 
the same as when using print capture. 
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versionNumber BYTE Version number of the print job’s client record 
area structure. Set to 0. 

tabSize BYTE Number of spaces tabs are expanded to. 
Range 1-18, default 8. 

numberOfCopies WORD Number of copies of the captured file to print. 
Range 0 to 65536, default 1. 

printControlFlags WORD See figure 19-12. 


maxLinesPerPage WORD Maximum number of text lines to print per page. 
maxCharsPerLine WORD Maximum number of characters fo print per line. 


BYTEL13] Name of the form that must be mounted on the 
printer before the captured file can be printed. If 
the correct form is not mounted, the print server 
console operator will be notified to mount the 
form. 

bannerNameField BYTE[13] User name to be printed on banner page. Must 
be null-terminated. 

bannerFileField BYTE[13] File name fo be printed on banner page. Must be 
null-terminated. 


headerFileField BYTE[14] File name to be printed on header 
of banner page. Must be null-terminated. 


directoryPath BYTE[80] Directory path to be printed on header of banner 
page. Must be null-terminated. 














Figure 19-11. Fields 
of the Client Record 
Area of a Print Job. 
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Figure 19-12. 
Definitions of Bits in 
the printControlFlags 

Field of the Client 
Record Area. 


Figure 19-12 describes the bit definitions of the printControlFlags field 
of the client record area. 


The print job is released for printing if the submitting workstation loses 






its connection to the file server. 


Suppress form feed after job is printed. 
Print service will interpret printing control settings (tab size, etc.). 


0x80 Print a banner page. 
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Well, I start now on foot, and get there before night... You will 
in the meanwhile have earned your fare, and arrive there 
sometime to-morrow, or possibly this evening, if you are lucky 
enough to get a job in season. 


—Henry David Thoreau, Walden 


A Make Server 


This chapter shows how to use QMS to create a make server. The make 
server is written for NetWare 2.x and 3.x, but will run under bindery 
emulation on NetWare 4.x. Users submit the path to a file, which the 
make server is to compile or link, or use as a make file to build a 
program. 
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To service jobs submitted by 
queue users, the make 
server program logs into 
the network as the make 
server object, retrieves jobs 
(stored in the queue 
directory) from the queue, 
and takes whatever action 
is appropriate in servicing 
the job. 


Make Server Bindery 
Object 





QMS Components | 


The make server consists of three main components: 
a make server bindery object, 

a make queue bindery object, 

a queue directory. 


Because these objects must be created before the make server can run, 
you must have an installation program that creates these objects on the 
file server that will manage the make queue. We have considerately 
written the installation program for you. 


To submit a job to a make server’s queue, a bindery object must be able 
to attach to the file server that has the make server’s queue object, and 
the bindery ID of the object submitting the job must be in the queue 
object’s Q_USERS property. A bindery object must have a 
LOGIN_CONTROL property to log in to a file server. When NetWare 
utilities create a user object, they add a LOGIN_CONTROL property to 
the object. Your make server’s installation or administration program 
determines which bindery objects can submit jobs to the queue, 
whether user objects, bindery objects of other predefined types, or 
custom objects that your program creates. 


To service jobs submitted by queue users, the make server program 
logs into the network as the make server object, retrieves jobs (stored 
in the queue directory) from the queue, and takes whatever action is 
appropriate in servicing the job. 


NetWare does not have a predefined bindery object type for make 
servers, so we will use an object type in the range Novell has reserved 
for experimental, third-party, or newly-defined objects (greater than 
0x8000). If you are going to release your application beyond your own 
development network, you should contact Novell Developer Support 
about registering your object type. 
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Because the make server object must log in to the file server, it must 
have a LOGIN_CONTROL bindery property. If accounting has been 
installed on the NetWare server, the make server must also have an 
ACCOUNT_BALANCE property with a credit balance (typically you 
would give a queue server unlimited credit). Figure 20-1 shows the 
properties of make server and make queue objects. 


Make Server Object 
LOGIN_CONTROL 


Password, password 
restrictions 


ACCOUNT_BALANCE 


Account balance, 
credit limit 







Figure 20-1. 
Properties of Make 
Server and Make 
Queue Objects. 


Make Queue Object 
Q_OPERATORS 


Bindery IDs of 


queue operators 


Q_USERS 


Bindery IDs of 
queue users 


Q_SERVERS 


Bindery IDs of 
queue servers 


Q_DIRECTORY 


Path of queue 











directory 
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Make Queue Bindery 
Object 


Queve Directory 





Figure 20-2. 
MAKEIT.H. 


The make queue bindery object controls who has what level of access to 
the queue; who can submit jobs, who can delete jobs from the queue, 
and who can service jobs. It also contains the path of the queue 
directory. 


Data associated with enqueued jobs is stored in files in the queue 
directory. The path of the queue directory is in the Q_ DIRECTORY 
property of the queue bindery object. Figure 20-2, a listing of 
MAKEIT.H, has common declarations for the programs that comprise 
the make server. 


define MAKESERV_NAME “MAKEIT” 

#define OT_MAKEIT 0x8020 

f#tdefine OT_MAKEIT_Q 0x8021 

#define MAKESERV_PWORD “MAKEMY PROGRAM” 

define MAKESERV_PATH "Sy O: V\ASYSTEM\A\MAKESERYV” 
#define MAKEIT_COMPILE 0 

define MAKEIT_LINK ] 

#tdefine MAKEIT_MAKE 2 


Note that we have defined three job types: compile, link, and make. The 
user specifies whether the make server is to compile, link, or run make 
on the specified source file by setting a command line parameter when 
running the program that submits the make job. 


Installing the Make Server 


The make server install program: 
Verifies that the queue directory exists, 
Creates the make server object in the bindery of the default file server, 


Creates a password property and assigns a password for the make 
server object, 
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Figure 20-3. 
Description and 
Simplifying 
Assumptions for 
MAKEIT.EXE. 


Checks to see if accounting is installed, and if so, creates an account 
balance property for the make server object and gives the object unlim- 
ited credit, 


Creates a job queue object, 


adds the currently-logged user ID to the queue’s Q_USERS and 
Q OPERATORS properties, 


adds the newly-created make server object to the queue object’s 
Q_ SERVERS property. 





Submitting Jobs for Service 


QMS jobs consist of a job structure and a file that contains the data the 
make server operates on. Programs that submit jobs to the queue must: 


Call NWCreateQueueFile2 to create the queue file, 
Fill in the fields of the job structure, 
Call NWCloseFileAndStartQueueJob2 to enqueue the job. 


The program that submits make jobs is MAKEIT.C, and a description of 
how to use MAKEIT.EXE and its simplifying assumptions is found in 
Figure 20-3. 


PROGRAM: MAKEIT.EXE 


DESCRIPTION: Submits either a .C, .OBJ, or .MAK file 
for processing. 


SYNTAX: MAKEIT CL /c | /1 | /m ] [parameter string] 

REMARKS: The first three switches tell MAKEIT 
whether the job being submitted needs to 
be compiled, linked, or “maked.” For 
example, 


makeit /c srcfile.c 


would compile SRCFILE.C into an .OBJ file. 
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The “parameter” string is passed directly 
to the compiler, linker, or “maker.” For 
example, 


makeit /c -p F:\USERS\WARREN\HELLO.C 


would compile the HELLO.C into HELLO.OBJ 
using the PASCAL calling conventions. 


SIMPLIFY DING 
ASSUMPTIONS: « MAKEIT assumes that the compiler, 
linker, or maker is already installed on 


Figure 20-3. the machine with the make queue. 
Description and 
Simplifying 
Assumptions for 
MAKEIT.EXE. 
(Continued) 
Figure 20-4 shows the declaration of the job structure, QueueJobStruct. 
As noted in the comments in the listing, the NWCreateQueueFile2 
function assigns values to some of the fields when your program calls 
the function to begin creating a job. 
typedef struct 
{ /* who assigns value to the field? */ 
BYTE clientStation; /* NWCreateQueueFile2 */ 
BYTE clientTask: /* NWCreateQueueFile2 */ 
DWORD clientID; /* NWCreateQueueFile2 */ 
DWORD targetServerlID; /* submitting program */ 
BYTE targetExecutionlTimeL6]; /* submitting program */ 
BYTE jJoObEntrylimel6]: 
/* NWCloseFileAndStartQueueJob2*/ 
WORD jobNumber; /* NWCreateQueueFile2 */ 
WORD jobType; /* submitting program */ 
BYTE JObPosition: /* OMS */ 
BYTE JoblLontrolFlags: /* submitting program */ 
BYTE jobFileName[14]; /* submitting program */ 
BYTE jobFileHandle[6]; /* submitting program */ 
BYTE servicingServerStation; (* OMS */ 
BYTE servicingServerlask; (* OMS */ 
DWORD servicingServerlID; c* OMS. #7 
BYTE jobDescriptionL50]; /* submitting program */ 
Figure 20-4. Queue BYTE clientRecordArea[152]; /* submitting program */ 
Job Structure. 


} QueueJobStruct;: 
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The clientRecordArea 
contains any data the 
submitting program wants 
to communicate to the 
make server relative to how 
the job should be handled. 
For example, NetWare 
printing uses this area to 
store print job parameters 
such as tab size, number of 


copies, and banner name. 


The client job submission program must assign values to the following 
fields: 


targetID, the bindery ID of the target server, 


targetExecutionTime, the earliest time the make server can service the 
job, 


jobType, a number identifying the type of the job entry; make servers 
can request a specific job type, or request a job of any type, 


jobControlFlags, bits that specify how the make server is to handle the 
job. 


The jobDescription and clientRecordArea are optional fields for use by 
the queue server. Typically, the jobDescription field contains a string 
that describes the contents of the job being submitted, for use by a 
program that displays or manages the progress of queue jobs. The 
clientRecordArea contains any data the submitting program wants to 
communicate to the make server relative to how the job should be 
handled. For example, NetWare printing uses this area to store print job 
parameters such as tab size, number of copies, and banner name. 


The remaining fields in the job structure are filled in by 
NWCloseFileAndStartQueueJob2 when your program submits the job, 
or by QMS as the job progresses through the queue. Your programs 
can call NWReadQueueJobEntry2 to read the job structure after the job 
has been submitted to the queue. 


- Servicing Jobs 





A make server logs in to the NetWare server on which the make server 
bindery object resides, calls NWGetObjectID to get the object ID of the 
queue object, and then calls NWAttachQueueServerToQueue. The make 
server can then service jobs in the queue. 
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The make server must have access to a compiler, include files, and 
library files, so it maps a drive to the subdirectory where these files are 
located. The make server assumes the directory structure shown in 
Figure 20-5. 


SYS Volume 
/ (Root) 


PROG 


BCOS2 


BIN INCLUDE LIB 


Figure 20-5. Directory 
Structure Assumed by 
Make Server. 


To service a job, the make server calls NWServiceQueueJob2, which 
returns the job’s job structure and the handle of the job file. When 
calling NWServiceQueueJob2, the make server can specify which job 
type it wants to service, or can specify job type -1 to indicate that the 
make server will accept a job of any type. 
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To preserve file server 
security, the make server 
should assume the client’s 
access rights before 
servicing the job. 


Because you are 
considerate of the needs of 
your customers, server 
programs you write will 
have an uninstall program 
that deletes the make server 
and queue objects from the 
bindery and deletes the 
queue directory. 


When servicing jobs, queue servers frequently have to access files 
besides the job file. To preserve file server security, the make server 
should assume the client’s access rights before servicing the job. The 
queue server does this by calling NWChangeToClientRights2 after 
getting the job to be serviced. If the queue server needs to access files 
with the rights of the make server, it can open them before assuming 
the client’s rights. 


After servicing a job, the make server calls NWFinishServicing- 
QueueJob2 to signal to QMS that the job can be removed from the 
queue. Ifthe make server is unable to service the job, it should then call 
NWaAbortServicingQueueJob2. Depending upon how the client set the 
jobControlFlags when it submitted the job, QMS will either delete the 
job from the queue or leave it in the queue, so that a server can make 
another attempt to service the job. The make server reverts to server 
rights when it calls either NWFinishServicingQueueJob2 or 
NWaAbortServicingQueuesob2. 


Before the make server terminates, it calls NWDetachQueue- 
ServerFromQueue, then logs out by calling NWLogoutFromFileServer. 





Uninstalling the Make Server 


The make server’s installation program creates the queue directory and 
bindery objects. Because you are considerate of the needs of your 
customers, server programs you write will have an uninstall program 
that deletes the make server and queue objects from the bindery and 
deletes the queue directory. The make server’s uninstall program is 
called (oddly enough) UNINSTAL.C. 


Another useful program would be a queue administration utility that 
would allow a queue operator to look at the jobs in the queue (the 
jobNumber, jobPosition, clientID, and jobDescription fields from the job 
structure), delete jobs from the queue, and move jobs within the queue. 
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NetWare’s accounting sys- 
tem is designed to allow 
network administrators 
charge users for services 

such as connect time and 
disk storage. You can also 
use NetWare accounting 
APIs to charge users for 
services provided by your 
programs. 





‘Item, it 1s my will that, touching certain moneys in the hands 
of Sancho Panza (whom in my madness I made my squire), 
inasmuch as between him and me there have been certain 
accounts and debits and credits, no claim be made against 
him, nor any account demanded of him in respect of them; but 
that if anything remain over and above, after he has paid 
himself what I owe him, the balance, which will be but little, 
shall be his...” 


—Miguel de Cervantes, Don Quixote 





Purpose of Accounting Services 





NetWare’s accounting system is designed to allow network administra- 
tors charge users for services such as connect time and disk storage. 
You can also use NetWare accounting APIs to charge users for services 
provided by your programs. For example, you could write a job server 
that charges users for each job it completes. 
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NetWare accounting is based on the NetWare bindery, so you should 
be familiar with bindery objects and properties before attempting to use 
accounting services in your program. 


NetWare accounting is very simple, which is part of the reason it is not 
frequently used. User accounts have a single balance from which the 
NetWare server deducts charges for all services. Suppose, for example, 
you write a print server that deducts one unit from a user’s account 
balance for each page printed. If the network administrator who installs 
your print server has set a charge of one unit per hour of connect time, 
then each page a user prints would reduce their allowed connect time 
by one hour (and vice versa). If you need to maintain a separate account 
balance, or if you need a more sophisticated accounting mechanism, 
you should write your own system, similar to the built-in system, that 
uses bindery properties (NetWare 3.x) or directory services properties 
(NetWare 4.x). 


If you are writing a program that provides a service to network users 
(like the Make server we present in “A Queue Management Services 
Sample Application” chapter), you should consider implementing your 
own system of accounting for service usage. An article in the January 
’94 issue of NetWare Application Notes gives the design for a custom 
accounting system. See “A Custom Accounting System for NetWare” in 
the “Developer Notes” section. 


The remainder of this chapter tells how to install and administer the 
accounting system, and describes the bindery properties, files, and 
APIs that make up NetWare accounting. The following chapter illus- 
trates one application of the accounting system by modifying the make 
server presented in the “A Queue Management Services Sample Appli- 
Before your program can cation” chapter, so that it charges for services. 
use the accounting APIs, 


the network administrator 





Installing and Using NetWare Accounting 


for the target file server 

must have installed 
Before your program can use the accounting APIs, the network 
administrator for the target file server must have installed accounting. 
To install accounting, you use different utilities, depending upon whether 
you are using NetWare 3.x or 4.x. Use the SYSCON utility to install 


accounting. 
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Setting Charges for 
NetWare Services 


accounting on a NetWare3.x file server. On a NetWare 4.x file server, use 
the NetWare Administrator utility (NWADMIN) for Microsoft Windows or 
OS/2 2.x or the NETADMIN utility for DOS. See the documentation for 
these utilities for the exact installation procedure. 


When one of the NetWare utilities installs accounting on a NetWare 
server it: 


Adds ACCOUNT_SERVERS, CONNECT_TIME, REQUESTS_MADE, 
BLOCKS_READ, BLOCKS_WRITTEN, and DISK_STORAGE proper- 
ties to the file server bindery object 


Adds ACCOUNT_BALANCE and ACCOUNT_HOLDS properties to 
each user object 


Creates a file called NETSACCT.DAT in the SYS:SYSTEM directory to 
hold accounting audit records 


Once you have installed accounting, you can set charges for NetWare 
services. You can set charges for: 


Disk blocks read 

Disk blocks written 

Connect time 

Disk storage 

Service requests 

On NetWare 3.x servers, select “Accounting” from the main menu. The 


“Accounting” menu, shown in Figure 21-1, contains submenu items that 
allow you to set charges for each of the chargeable NetWare services. 
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SYSCON -3. 62 Wednesday February 2, 1994 1:21 pm 
User MADAIR On File Server MBA 


Available Topics 


a Ng 
Accounting urrent Server 


ver Information 
Accounting Servers Formation 
Blocks Read Charge Rates 
Blocks Written Charge Rates 
Connect Time Charge Rates 
Disk Storage Charge Rates 
Service Requests Charge Rates 





Figure 21-1. 
SYSCON’s Accounting 
Menu. 


For NetWare 4.x servers, run NWADMIN and double-click on a 
NetWare server object to open the “Details” window for the server 
(shown in Figure 21-2). You can then click on buttons in the window to 
set charges for each of the chargeable services. 
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Figure 21-2. 
NWADMIN's Details 
Window for a Server 

Object. 


Accessing Accounting 
Data 


Identification 


Name: SJF-CPS.CPS.OPS.Novell 


Other Name: 


Description: 


Location: 

Department: 
Organization: 
Net Address: 


Status: Up 


Version: Novell NetWare v4.02[DS] 





The NetWare utilities that set rates for chargeable services store the 
charge rates in bindery properties corresponding to each service. 
Names of the properties are: 


CONNECT_TIME 
REQUESTS_MADE 
BLOCKS_READ 
BLOCKS_WRITTEN 
DISK_STORAGE 


Two utilities can extract the accounting audit data from the accounting 
files. PAUDIT displays the data in each entry in the NETSACCT.DAT 
file according to the record format stored in NETSREC.DAT. Both files 
are kept in the SYS:SYSTEM directory. ATOTAL calculates daily and 
weekly totals for each of the chargeable services. ATOTAL summa- 
rizes usage for the file server; charges are not itemized by user. 
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Although PAUDIT works with either NetWare 3.x or 4.x, Novell did not 
include the utility with NetWare 4.0 or 4.01. If you have both NetWare 
3.x and 4.x servers and you plan to use NetWare’s accounting system, 
you may want to copy PAUDIT to your NetWare 4.x servers. 


The following chapter presents a program that reads accounting 
records from the NETSACCT.DAT file. 





Accounting Services Functions 


There are only five Accounting Services functions. They are summa- 
rized in Figure 21-3. 


Function | Parpose 
NWGetAccountStatus Get the account balance, account limit, and 
holds on a specified bindery object. 
NWQueryAccountingInstalled Determines whether accounting has been 
installed on a NetWare server. 


NWSubmitAccountCharge Make a charge against a user's account. Also, 
relinquish a hold against a bindery object’s 
account, if one was made. 





















NWSubmitAccountHold Reserve a specified amount from a bindery 
object's account, before providing the service 


for which the object is to be charged. 





NWSubmitAccountNote Add a note about an accounting transaction to 


Figure 21-3. the audit record. 
Accounting Services 


Functions. 
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Accounting Servers 


Account Status 


Before your program can charge for services, its bindery ID must be in 
the ACCOUNT_SERVERS property of the NetWare file server to which 
the charge will be submitted. Your program, therefore, must have a 
bindery object created for it, have that bindery object’s ID added to the 
file server's ACCOUNT_SERVERS property, log in to the file server as 
the bindery object, and submit account charges for users on that file 
server who use the services provided by your program. If you want to 
provide a service for which a well-defined bindery object type (for 
example, job server, print server, archive server) does not exist, you 
should contact Novell to register your bindery object type. See the 
Bindery Services Theory chapter for more information. 


Typically, a program that uses accounting will have an installation 
program that creates the program’s bindery object (using 
NWCreateObject), adds the object ID to the file server’s 
ACCOUNT_SERVERS property (with NWAddObjectToSet), and assigns 
a password (NWChangeObjectPassword). The installation program must 
be run by SUPERVISOR or a SUPERVISOR-equivalent user. The server 
part of your program could run on a dedicated workstation, or as a task 
running in the background in a private OS/2 session. 


NWGetAccountStatus returns information about a bindery object’s ac- 
count. Your program passes the name and type of the bindery object for 
which you are requesting information. NWGetAccountStatus returns 
the object’s account balance (in arbitrary accounting units), the object’s 
credit limit, and a NWHOLDS_ STATUS structure, which contains an 
array of up-to-16 NWHOLDS_INFO records, as defined in NWACCT.H. 


typedef struct 

{ 
NWOBJ_ID objectID; 
NWACCT_BALANCE amount; 

} NWHOLDS_INFO; 


typedef struct 
| 
NWACCT_HOLDS holdsCount; 
NWHOLDS_INFO holds[16]; 
} NWHOLDS_STATUS; 
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Account Holds 


Account holds guarantee 
that an object will have 
sufficient credit when a 

charge is made to the 


object’s account. 


Account Charges 


Account holds guarantee that an object will have sufficient credit when 
a charge is made to the object’s account.For example, if you have a job 
server that charges ten units to service a particular job type, when a 
user submits a job for service, your job server could call 
NWGetAccountStatus to check the user’s account balance, credit limit, 
and the amount of holds on the user’s account. If the user has sufficient 
credit, your server would then place a hold on ten units on the user’s 
account. When your server is done servicing the job, it would then 
submit a charge of ten units to the account and cancel the hold on ten 
units. If your server is unable to service the job, it can call 
NWSubmitAccountCharge to release the hold against the account with- 
out making a charge against the account. 


NWSubmitAccountCharge makes a charge against a bindery object’s 
account. At the same time, you can use the call to release a hold you 
have previously made against the account. When your program calls 
NWSubmitAccountCharge, it must specify: 


the bindery ID and object type of the object whose account it is 
charging, 


your server’s bindery object type, 
the amount of the charge, 
the amount of the account hold to be cancelled (if any), 


the type of charge being made (which the NetWare Client API for C 
SDK documentation confusingly refers to as the noteType), 


and a comment record (which the SDK calls a note) corresponding to 
the charge type (or noteType). 


The comment record is a structure that contains any data you want to 
store in the NETSACCT.DAT file with the charge entry. For example, 
when a NetWare server makes a disk storage charge, the comment 
record contains the number of disk blocks and half-hour periods of 
ownership the user is being charged for. 


There are two Novell-defined charge types, connect time charge and 
disk storage charge (see The NET$ACCT.DAT File section later in this 
chapter). To create your own charge type, you must define the structure 
of the comment record data. You should also add an entry to the 
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Account Notes 


NETSREC.DAT file that tells PAUDIT and other audit programs how to 
interpret the data in your comment record. See The NET$REC.DAT 
File section below for more information. If you plan to sell your 
program, you should register your charge type with Novell. Contact 
Novell’s Professional Developers’ Program at 1-800-NETWARE or 
1-801-429-5588. 


Your program can submit account notes to be entered in the 
NETSACCT.DAT file. No changes are made to a user’s account bal- 
ance. When your program calls NWSubmitAccountNote, it specifies: 


the bindery ID and object type of the object to which the note pertains, 
your server’s bindery object type, 

the note type, 

and a comment record corresponding to the noteType. 

The comment record is identical to an account charge’s comment 
record. Novell defines six types of notes: login, logout, intruder detec- 


tion account lock, server time changed, server booted, and server 
downed. 





The NETSREC.DAT File 


The NETSREC.DAT file contains strings that PAUDIT and other ac- 
counting audit programs use to format comment records from charge 
and note entries in the NETSACCT.DAT file. The file contains strings 
that are formatted for output by printf and other stream-oriented C 
functions. Each string in NETSREC.DAT is stored in a data structure 
that also specifies the number and type of data fields that the string 
expects to have passed with it to printf. Figure 21-4 shows the fields in 
each format string record in NETSREC.DAT. 


The connect time format string is: 


Connected 4lu minutes: 4lu requests; £04x%Z04x%04xh bytes 
read; 404x%Z04xZ04xh bytes written 
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When you use prinifto print this string, printf will expect 8 data items to 
be passed to it to be formatted and inserted into the string, two DWORD 
(4-byte) values and six WORD values. The fteldCount value for the 
connect time record in NETSREC.DAT, therefore is 8. Following the 
fieldCount field in the record, there will be eight BYTE values specify- 
ing the type of each field. The first two bytes will be set to 3, for 
DWORD, and the following six will be 2, for WORD. 


ee 


WORD | length length (in bytes) of the remaining fields in the record. 


WORD _ ___ Comment type. 
1 = Connect time charge 
2 = Disk storage charge 
3 = Login note 
4 = Logout note 
5 = Account locked note 
6 = Server time modified note 
7 = Object rights changed 
8 = Server booted 


fieldCount Number of data items in formatted string (see 
explanation below). 





BYTE 
[fieldCount] datalype Type of each data item. 
1 = BYTE 
2 = WORD 
3 = DWORD 
4 = STRING 
(length-preceded) 
formatStringLength Length of the following format string. 
BYTE 
[formatStringLength] formatString The format string. 
Figure 21-4. 
Format String Record 
Structure in 
NETSREC.DAT. 
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Whenever NetWare file 
servers or other accounting 
servers submit accounting 
charges or notes, NetWare 
makes an entry in the 
NET$ACCT.DAT file. 





The NETS ACCT.DAT File 


Whenever NetWare file servers or other accounting servers submit 
accounting charges or notes, NetWare makes an entry in the 
NETSACCT.DAT file. Each entry is one of the two Novell-defined 
charge records, or one of the six Novell-defined note records, or charge 
or note records that have been submitted by your programs. 


The NETSACCT.DAT file grows forever, so you should archive it or 
delete it periodically. NetWare will create a new file when it has a new 
charge or note to enter. 


Figure 21-5 shows the structure of the NETSACCT.DAT file. 
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Accounting Record Connect Time Charge Comment 
perp length --------4 Leek he eee, 
b------- serverlID-------- ee ett teeta 
| ....-timeStamp----- 
er a 
Semplaioncads 
Pras service Type-----+ 
PE pe ee Sy eg el apersces ---bytesWritten2.--- 
Bint ata ee r --bytesWrittenLo -- 











Note Structure 


NoteType ~~~~~~ 





Figure 21-5. 
Structure of the 
NETSACCT.DAT File. 


300 OS/2 and NetWare Programming: Using the NetWare Client API for C 








Read thy book, thou art accountant enough against thyself 
to-day! 


—The Koran 


An Accounting Server 





To illustrate the basics of NetWare Accounting, we’ll modify the make 
server presented in the “Queue Management Services Sample Applica- 
tion” chapter to charge for its services. Charging for services is rela- 
tively simple, requiring us to add just a few lines of code to two of the 
programs that comprise the make server. 
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When you install 
accounting on a file server, 
NetWare adds a set 
property to the file server 
object. The property, 
ACCOUNT_SERVERS, 
contains the object IDs of 
all objects that are 
authorized to make charges 
against users’ account 


balances. 


Figure Figure 22-1. 
Bindery Objects and 
Properties for an 
Accounting Server. 


Installing and Uninstalling 





The only change in the make server installation procedure is to add the 
make server’s object ID to the ACCOUNT_SERVERS property of the 
file server on which you are installing the make server. When you 
install accounting on a file server, NetWare adds a set property to the 
file server object. The property, ACCOUNT_SERVERS, contains the 
object IDs of all objects that are authorized to make charges against 
users’ account balances. Figure 22-1 shows the objects and properties 
that must be added to the bindery to allow an application to charge for 
Services. 


Object: Abraham 
Type: OT_FILE_SERVER 
ACCOUNT_SERVERS Property 


00134FFF Bindery ID of 


MAKEIT Object 


Object: MAKEIT 
Type: OT_MAKEIT_Q 


Q_DIRECTORY Property 





Directory path where 
QMS places queue job 


Q_SERVERS Property 


Bindery IDs of objects 
authorized to service 
queue jobs 


Object: MAKEIT 
Type: OT_MAKEIT 


LOGIN_CONTROL Property 





Q_OPERATORS Property 


Bindery IDs of queue 


Password (encrypted) operators 


ACCOUNT_BALANCE Property 
Balance Q_USERS Property - 


Credit Limit Bindery IDs of users 
who can place jobs in the | 


Use the function NWAddObjectToSet to add the make server object to 
the file server’s ACCOUNT_SERVERS property. The code to be added 
to INSTALL.C is shown in Figure 22-2. 


302 OS/2 and NetWare Programming: Using the NetWare Client API for C 


Figure 22-2. 
INSTALL.C 
Modifications to Allow 
the Make Server to 
Charge for Services. 


Placing a hold on the 
account 1s optional, but 
assures that the user will 
have sufficient credit when 
the server is done servicing 
the make job. 


/* set up make server to charge for services */ 

/* first get name of default server */ 

ccode = NWGetFileServerName(connID, serverName) ; 

if Cecode J= SUCCESSFUL) { 
printf(“Unable to get name of default server\n”); 
exitt=1)% 

} 


/* add make server to file server’s ACCOUNT_SERVERS property */ 
ccode = NWAddObjectToSet(connID, serverName, OT_FILE_SERVER, 
“ACCOUNT_SERVERS”, MAKESERV_NAME, 

OT_MAKEIT); 
1t (ccode J= SUCCESSFUL) { 

printf(“Unable to add make server to ACCOUNT_SERVERS 
property\n”); 

exitte-1): 
} 


Since the install program verifies that accounting has been installed on 
the default file server (so that it knows whether to create an 
ACCOUNT_BALANCE property for the make server object), you can 
call NWAddObjectToSet after calling NWQueryAccountingInstalled. If 
accounting has not been installed, there will be no 
ACCOUNT_SERVERS property to add the make server object to. 


We do not have to make any changes to the uninstall program. When 
the uninstall program deletes the make server object, NetWare also 
deletes it from the server’s ACCOUNT_SERVERS property, so the 
uninstall program does not have to do it explicitly. 


Account Holds and Charges 


When the make server program services a job, it places a hold against 
the account of the user who submitted the job. When the make server 
has finished servicing the job, it releases its hold on the account and 
submits a charge against the account. The server must place its hold on 
the account before assuming the client’s rights. Placing a hold on the 
account is optional, but assures that the user will have sufficient credit 
when the server is done servicing the make job. The make server could 
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charge the user’s account before servicing the job, but if the server is 
unable to service the job, it would have to (if it is a polite program) 
credit the user’s account, a more complicated process than placing a 
hold on the account. 


The code in Figure 22-3 shows how to place a hold and submit a charge 
to a user’s account. Note that the NWSubmitAccountCharge function 
cancels the account hold at the same time it charges the user’s account. 


/* submit hold against user’s account */ 
ccode = NWSubmitAccountHold(connID, objectType, userName, 1); 
if ((ccode == LOGIN_DENIED_NO_ACCOUNT_BALANCE) | | 
(ccode == LOGIN _DENIED_NO_CREDIT)) | 
gotoxy(1, currLine); 
printt("insufficient credit\n”™):; 
currLinet+; 
} else if (ccode == ERR_TOO_MANY_HOLDS) { 
gotoxy(l, currLine); 
printf(“Too many holds against account\n”); 
CUPPLINGTSs 
} else { 
/* assume rights of client who submitted the job */ 


/* service the job */ 


/* submit charge against account */ 
ccode = NWSubmitAccountCharge(connID, objectlype, 
userName, 
OT_MAKEIT, 2, dy @ NULL: 
if (ceode [= SUCCESSFUL) { 
gotoxy(l, currLline); 
curr liner: 
printf(“Unable to submit charge, ccode = 4Xh\n”, 
ccode); 


Figure 22-3. 
MAKESERV.C 
Modifications to 
Submit Charges for 
Services. 





304 OS/2 and NetWare Programming: Using the NetWare Client API for C 





To simplify the program, we do not submit an account note when we 
make the charge to the user’s account. A “real” program should submit 
an account note, so there will be an entry in the accounting audit file 
that tells who made the charge against the user’s account and why. If 
you are going to sell your application, you should contact Novell’s 
Professional Developer’s Program (PDP) and register your account 
note type, so auditing programs can decipher your account notes. 


Suggested Enhancements 





Once you have modified the make server to submit account notes, the 
program will need an audit utility that reads the accounting audit file 
and extracts and summarizes account notes that were submitted by the 
make server. You may also want to add an account balance administra- 
tion utility, so that the make server administrator can modify user’s 
account balances without running SYSCON, NWADMIN, or 
NETADMIN. 
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Let not thine own passion blind thee...for the errors thou wilt 
thus commit will be most frequently irremedtable. 


—Miguel de Cervantes, Don Quixote 


If you are implementing a database or spreadsheet, you may have 
updates to multiple fields that all require that the changes happen at the 
same time. This set of changes would be defined as a transaction. 
NetWare Transaction Tracking Services (TTS) makes it possible for 
you to define transactions and then commit them or cancel them as a 
group. When a server is tracking transactions, it will do rollbacks if they 
are never committed. If, while you are using a database application that 
groups modifications into transactions, the server goes down, it will 
void any changes not committed as a full transaction. Transaction 
tracking provided by NetWare servers helps decrease the possibility of 
data corruption. 
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What is Transaction Tracking? 





NetWare servers contain the logic necessary to implicitly or explicitly 
track groups of actions and save or abort their results all at once. 
Implicit transaction tracking is triggered on a connection or process 
basis. The tracking begins when the number of physical or record locks 
you place on a file that is marked as transactional reaches either a per- 
process threshold or a per-connection threshold. These thresholds are 
set through the NetWare utilities or, programmatically, through the 
TTS application programming interface. You can control this threshold 
and not be required to do any additional work for the file to be tracked. 
For TTS to track a file, the file must have the Transaction attribute set. 
See the “NetWare File System Services Theory” chapter in this book to 
learn how to get the file attribute information. 


Explicit transaction tracking requires that you make the decisions as to 
when a transaction begins and ends. This logic is very easy to use and 
has the basic database/spreadsheet functionality of begin transaction, 
commit transaction, and abort transaction. Using the function calls to 
perform these operations, you won’t need to build your own “commit 
cache” into your application, you can let the NetWare server do all the 
work. If the server is tracking the transactions, the database integrity is 
not dependent on whether or not your write request made it to the 
server in time. If the network or the server goes down and the server 
has not implicitly or explicitly been notified that the transaction 
completed, the server will roll out the initial changes made as part of the 
transaction. Thus, data integrity is maintained in the physical data file. 
After discussing how TTS actually works, we’ll explore the function 
calls in greater detail. 


The Mechanics of the Transaction 


Tracking System — 





Whether the transaction is implicit or explicit, TTS is able to track up to 
200 transactions at atime. A configuration option on the server allows 
the network administrator to control the number of transactions TTS 
tracks. This option can be set to any value from a minimum of 50 to a 
maximum of 200. When tracking requests, TTS will take the following 
steps: 
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Begin Transaction 


End Transaction 


1) Cache the change requests, 
2) Read the data to be changed from the file, 
3) Save the original data to a work file, and 


4) Write the changes to the file. 


If, before the transaction is ended, the server or the application goes 
down, the changes can be rolled back by TTS. This will be done by 
replacing the changes in the file being tracked with the original data 
saved to the work file. If you are using implicit transaction tracking, the 
work file could easily become huge on a heavily used database. With 
explicit tracking, you control which writes you really want tracked. 
Although this doesn’t necessarily imply the work file won’t be large, 
only the data your application requires saved will be in the work file, 
instead of every write. 





Explicit Transaction Tracking 


Explicit transaction tracking requires you to make use of three function 
calls: NWTTSBeginTransaction, NWTTSEndTransaction, and 
NWTTS<AbortTransaction. These functions will track all write requests 
between the begin and the end. If an end call is not received and either 
the server or the client go down, then the transaction will be aborted 
and “rolled back” to the original data. 


The NWTTSBeginTransaction function call allows you to explicitly force 
transaction tracking to begin. All the writes you do to your files after 
this call will be considered part of the transaction. To close the transac- 
tion, you must either call NWT7TTSEndTransaction to commit your 
changes or NWTTSAbortTransaction to cancel your changes. 


The NWTTSEndTransaction function call will commit any changes 
made to your files by your application since calling the 
NWTTSBeginTransaction function. This call will cause the data 
changes currently cached for your file to be written to the target file on 
the server disk. 
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Abort Transaction 


Calling NWTTSAbortTransaction will cause any changes made to the 
files at any point after calling NW7TTSBeginTransaction to be replaced 
in the cache with the original data stored in the work file. 


TTS Status and Availability 





You are provided with two calls to check on TTS availability and the 
status of a_ transaction, NWTTSTrvansactionStatus and 
NWTTSIsAvailable. NWTTSIsAvailable is a boolean call. If the return 
code is 0x89FF, TTS is available. If the return code is 0x0000 (FALSE), 
TTS is not available. The NW7TTSTyvansactionStatus call will tell you if 
an individual transaction has been committed to disk yet. This call 
takes the transaction number returned from NWTTSEndTransaction 
and the connection handle in order to specify which transaction is of 
interest. 


TTS Control Flags | 


The TTS control flags determine whether a file marked transactional is 
automatically locked when the application writes to it. In the 
NWTTSGetControlFlags and NWTTSSetControlFlags use a flag with the 
values of 0x00 for disabling automatic record locking and 0x01 for 
enabling automatic record locking. These calls only work on files that 
are flagged transactional. 





Implicit Transaction Tracking 


Implicit transaction tracking occurs after the number of files locked by 
the connection or process has reached the number set. If you always 
keep a configuration file open, you would want to have the thresholds 
set to one more than when you actually wanted tracking to begin. Using 
the calls NWSetConnectionThresholds and NWSetProcessThresholds can 
set the number of locks to reach before tracking begins. If you want to 
find out what level you currently have set, you can call 
NWGetConnectionThresholds and NWGetProcessThresholds. 
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Figure 23-1. 
Psuedo-code for TTS. 





Enabling and Disabling TTS 


NWTTSEnable and NWTTSDisable can be used by your application to 
only turn on TTS while you need it and turn it off when you don’t. To 
write your application to take advantage this feature, you need to make 
the enable call during initialization of your application. Shutting TTS off 
when it is not necessary will improve performance on the server. 


Using TTS—An Example 


The example code for TTS demonstrates the order and relation be- 
tween the different function calls. In Figure 23-1, we see that the first 
step for using TTS is to verify that it is enabled on the file server 
(NWIsTTSAvailable). It would also be helpful to verify whether the files 
are marked as transactional. The “NetWare File System Services 
Sample Application” chapter in this book has code demonstrating how 
to get the attribute information of files. 


Get your default connection 
Check if TTS is available 


IF not available 
[ Enable TTS 


Call NWT TSSetConnectionThresholds 
Call NWI TSSetProcessThresholds 


//Demonstrate Explicit tracking 
Call NWT TSBeginTransaction 


IF error 
| Print error message 
IF user cancels 
Call NWTTSAbortTransaction 


ELSE 
[ean NWT TSEndTransaction 
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If TTS is available, then we can set our thresholds for implicit tracking 
or call NWTTSBeginTransaction. If you only have specific operations 
that require files to be updated together, using explicit transaction 
tracking will give you better performance than tracking the files implic- 
itly. Most shared databases however, need constant and full transac- 
tion tracking to protect data integrity. 
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IPX is a datagram or 
connection-less 
communications protocol. 





For my part, I could easily do without the post-office. 


—Henry David Thoreau, Walden 


Internetwork Packet Exchange (IPX) is a high speed communications 
protocol designed by Novell. The basis of all communication in the 
native NetWare environment, whether between servers and worksta- 
tions, servers and servers, or workstations and workstations, IPX is a 
datagram or connection-less communications protocol. Sequenced 
Packet Exchange (SPX) is a guaranteed delivery protocol written by 
Novell, but modeled on the Sequenced Packet Protocol (SPP) designed 
by Xerox. However, SPX does not have a sliding window or sparse 
acknowledgements. 


IPX and SPX can be used for creating client/server or peer-to-peer 
applications. Client/server applications have a server providing a ser- 
vice which sits around awaiting for requests for that service. Applica- 
tions that are peer-to-peer in nature would allow equal bi-directional 
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access with either peer (workstation) initiating communication. 
NetWare 3 and 4 are examples of a client-server service applications. 
NetWare Lite and Personal NetWare are examples of peer-to-peer ser- 
vice applications. 





Programming Distributed Applications 


Before programming with IPX or SPX, you need to make the following 
decisions: 


1) Is the application is workstation-based or server-based? 


2) What is the most efficient method of passing data back and forth 
between the distributed pieces of the application? 


3) What format will the packets use to pass the data? 
4) Will the application be synchronous or asynchronous in nature? 
o) Will the application do batch processing or real-time processing? 


Depending on the answers to these questions, you may decide to use 
QMS or even extended NCPs for your application instead of using IPX. 
Or you may decide to use SPX rather than IPX. 


Process Distribution To decide whether your application should be workstation-based or 

and Location server-based, the basic purpose of the application should be evaluated. 
An application on the network shares a resource or provides a service. 
The provided service itself becomes a resource. The application needs 
to be placed wherever the resource is. The resources may be on a 
central server or on several machines within a workgroup. When the 
data is to be located on a central server, the application will provide 
more efficient service if it is located at the server as an NetWare 
Loadable Module (NLM). Ifthe resource is a set of data or a service on 
several workgroup machines, then the application will need to be lo- 
cated on each workstation. 
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Choosing your Protocol 


Locating a service on a workstation allows distributed processing inde- 
pendent of the NetWare server and allows you complete freedom to 
control all communication as well as allowing you to define all aspects of 
the distributed processing performed by your application. This model 
allows two non-server machines to communicate directly, resulting in 
an increase of speed. However, the complexity of direct workstation-to- 
workstation communications also becomes your full responsibility. 
This is not to discourage anyone wanting to use communications proto- 
cols, but is intended to let you know that the work you will be doing is 
more complex than simply calling library functions. 


Once you know where you are going to distribute the pieces of your 
application or service, you have to choose the protocol you are going to 
use to issue and to reply to requests between the endpoints. Protocol 
here is used in the general sense of a defined method by which informa- 
tion is communicated. You can use a centrally located file on a NetWare 
server, QMS, extended NCP, or communications protocols for your 
application to communicate. Whichever method you choose, your appli- 
cation will have different dependencies and requirements. 


If you choose to use a centrally located file on the NetWare server, your 
application will be dependent on the server being up and being avail- 
able. Your application performance will be bound by how busy your 
server and your network are and you will need your installation pro- 
gram to set up user rights and restrictions on the NetWare server. You 
will have similar restraints if you use QMS. Additionally, if you use 
QMS, you will need to set up a queue for your applications to use. 


If you choose to use extended NCP services for communications be- 
tween the ends of your application, you will need to write an NLM to run 
on the server. Either this NLM will need to be deployed on all servers 
and will in turn communicate with software components installed where 
the resources are available; or the NLM will need to advertise its 
presence on the network. The application on the workstation end will 
need to locate the NLM it needs to talk to and connect to the right 
server. 


Any of the above three options requires a NetWare server to be avail- 
able to “referee” the communications between the different pieces of 
your application. On the other hand, Novell provides IPX, SPX, 
NetBIOS, and Named Pipes for applications to use in distributing pro 
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Protocols and 
Networking Standards 


Figure 24-1. OSI 
Layers and 
Corresponding 
NetWare Software. 





cessing on the network. These communications protocols allow 
applications to communicate between nodes without requiring a 
NetWare server or any access to resources on a NetWare server. Each 
of these protocols lives on various levels of the OSI model discussed in 
the “Introduction to Networking and NetWare” chapter at the beginning 
of this book. 


IPX operates at the Network layer of the OSI model (Figure 24-1). SAP 
and RIP are also contained at this level. As a connection-less protocol, 
IPX makes no guarantee as to the reception of the data. SPX works on 
the Session and Transport layers of the OSI model as illustrated in 
Figure 24-1. Other Novell-supported protocols compare to the OSI 
model as seen in Figure 24-1. 


OSI Layer NetWare 


Application 


NetWare C Interface 
Presentation 


Session 


Transport 


Data Link MLIDs 
(e.g. NE200) 


Physical LAN Cards 
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Using IPX 


Using SPX 


Using NetBIOS or 
Named Pipes 


As a connection-less protocol, IPX doesn’t guarantee the delivery of 
packets to the destination. The data will be directed to the proper 
workstation, but the sender will not receive any confirmation of receipt 
of the data. When this protocol is used, the programmer has the 
freedom to implement whatever method is most efficient for the appli- 
cation to maintain communications between the workstations. The 
packet structures you create when you use [PX will be a very special- 
ized and optimized protocol for your application. Using IPX will also 
require you to define your own methods for guaranteed delivery and for 
sequencing of the data into the proper order. 


Because SPX is a connection-oriented protocol, it provides you with 
guaranteed delivery and session maintenance. This will reduce the 
complexity of the code you would write compared to creating an IPX 
application that did these two things. You still have the freedom of 
control to implement your application as efficient as possible by defin- 
ing your own packet formats and sizes. Again, the packet structures 
you create when you use SPX will be a very specialized and optimized 
protocol for your application. 


NetBIOS provides similar services to IPX and SPX, as does Named 
Pipes. These two protocol interfaces also allow you to write applications 
that run on non-NetWare networks as well. These interfaces are natively 
supported by the OS/2 operating system. Novell networks support 
these interfaces as well with device drivers written that work running 
over IPX. 


Choosing Your Processing Mode | 





Choosing to implement an application using batch processing or real- 
time processing will depend upon the kinds of resources provided. For 
example, file servers and database servers must be real time because 
the clients are using the information in real time. However, you can 
implement a print server, fax server, or make server using batch pro- 
cessing because the users won’t need to wait any longer for the job to 
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complete. Whether an application will be synchronous or asynchronous 
may also be determined by how it is to be used. If the information or 
service requested from the application is necessary before the user can 
proceed, then the application can be a combination of asynchronous on 
the network and synchronous for the user or fully synchronous for the 
user and on the network. Ifthe service provided by the application can 
occur in the background while the user continues to do other work, the 
application can be fully asynchronous both on the network and to the 
user. 





Data Enveloping and Packet Formats 


A packet is generally divided into sections that represent the software 
layers or protocols that it has passed through. The data an application 
wants to send is the first section. As this data is handed down to the 
next software layer, information pertinent to that layer is added to it. 
This continues until the packet is placed on the physical network by the 
LAN card. This adding of information is called enveloping. For ex- 
ample, if an application requests an open file from the file server it is 
enveloped with an NCP header, then an IPX header, and finally an 
Ethernet header (on an Ethernet network). This is illustrated in Figure 
24-2. 
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Figure 24-2. Data 
Enveloping. 





Data to be sent 


NCP Header 


Data to be sent 
enveloped by NCP header 


IPX Header 


Data to be sent 
NCP Header enveloped by NCP header 


owe and IPX header 


Ethernet Header 


Data to be sent 
IPX Header enveloped by NCP header 
and IPX header 


and Ethernet Header 
NCP Header 





The packet format, or the format of the data portion of the packet, is 
defined according to how the application needs to receive data. You 
could design your packets to send one piece of data at a time regardless 
of the packet size. This obviously would generate more packets than if 
the data were sent all at once in the biggest packet possible. Sending 
packets that are smaller than the maximum reliable packet size would 
obviously increase the amount of time your application has to wait for 
the request or reply to complete. It is equally obvious that sending 
larger than the maximum reliable packet size for your media will create 
errors and delays in processing as well. 
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An event control block 
contains the necessary 
information for IPX to send 


or receive a packet. 


Figure 24-3. The IPX 
ECB Structure. 





Programming IPX 


Once you have decided how you want to architect your application, you 
are ready to choose your protocol and to use it. Let’s talk about what you 
need to know to use and understand IPX and SPX. This information can 
help you decide when one of them is the best alternative for implement- 
ing your application. 


The IPX Event Control Block (ECB) 





All IPX packets and actions are called events and are controlled by an 
Event Control Block (ECB). An event control block contains the 
necessary information for IPX to send or receive a packet as well as how 
to schedule asynchronous events. The ECB has the structure shown in 
Figure 24-3. A list of the IPX functions is found in Figure 24-4. 


typedef struct 
{ 


void NWPTR fragAddress; 
UINT16 fraqgsize: 
} EVLBPRrag: 


typedef struct IPX_ECBStruct 
{ 


Struct IPX_ECBStruct NWPTR next; 
Struct IPRECBStruct NWPIR prev; 
UINT16 Status; 
long reservedl; 
UINT16 |ProetiIv: 
unsigned char protloLelds: 
UINT16 boardNumber; 
unsigned char immediateAddress[6]; 
unsigned char driverWSL4]; 
unsigned char protocolWSL8]; 
UINT16 dataLen; 
UINT16 fragCount; 
ECBFrag fraglistiz2]: 
}LPALEGB: 
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Figure 24-4, OS/2 
IPX Function Calls. 


The next and prev 
Fields 


The status Field 


The reserved! Field 


The Socket Field 


IpxCheckReceive 
IpxCheckSocket 
IpxCloseSocket 
IpxConnect 
IpxDisconnect 
IpxGetInternetworkAddress 
IpxGetLocalTarget 
IpxGetStatistics 
IpxGetVersion 
IpxOpenSocket 
IpxReceive 
IpxSend 


The next and prev fields are used internally by IPX to create a doubly 
linked list of ECBs. Each of these fields is a 16-bit far pointer. If the ECB 
is not in use by IPX, this field can be used by the application. You can 
tell if the ECB is in use by checking the status field. 


The status field indicates that the ECB is in use or not in use by IPX and 
the status of the event upon completion. A non-zero value for this flag 
indicates in use or an error condition. The errors for IPX all begin with 
0x90 or 0x80 in the high-order byte of the status field. No fields should 
by modified by the application while the ECB is in use by IPX. This field 
is a two byte field or UINT16 field. For a detailed list of IPX completion 
codes, see the header file IPXERROR.H. 


The reserved] field is reserved for use by IPX. 


The Socket is the source socket to use for the connection. The socket is 
a de-multiplexing mechanism. The socket is a word value that is in high- 
low order. The high-low order is necessary, because this the socket 
number IPX places in the packet header. The entire packet header is in 
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The profiD Field 


The boardNumber Field 


The immediateAddress 
Field 


high-low word order. The IPX header is in high-low word format 
because the protocol was originally designed on machines using the 
Motorola 68000 processor where the word format is high-low 
(big-endian). 


The socket number could be compared to an apartment number in an 
addressing scheme. The network number is similar to the street, the 
node address to the building number. The socket functions much like 
an apartment number by further resolving the process to which the 
packet should be directed in the node, the way a letter is directed to an 
apartment in a building. 


The protID field is the node address of the board specified by the board 
number. This node address is used by IPX along with the network 
number to create an internetwork address. 


The boardNumber field specifies which LSL board number to which IPX is 
bound that the application wishes to use to send or receive this packet. An 
LSL board number is a logical entity. It represents the particular standard 
frame types or link level protocols that are supported by the individual 
hardware topologies. For example, Ethernet standards include 802.2, 802.3, 
and Ethernet II. If the device driver for a particular Ethernet board 
supported all three of these standards simultaneously, than three logical 
boards would be available for IPX to use. 


The immediateAddress field is the value returned from 
IpxGetLocalTarget. The immediate address is the 6-byte node address 
of the nearest router that is aware of the destination address. The 
nearest router is assumed to be the first one to respond to the 
workstation when l[pxGetLocalTarget sends out the routing information 
broadcast. More about routing and routing broadcasts can be found in 
the Service Advertising and Routing Theory chapter in this book. This 
field must be filled before a packet can be sent. You can get the 
immediate address by using either the [pxGetLocalTarget procedure or 
by receiving a packet with [pxListenForPacket. Unless the destination is 
on the local net, a packet is set to the destination via the routing node 
that has information concerning the route to the destination. 
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The driverWS Field 


The protocolWS Field 


The datalen Field 


The fragCount and 
fraglist 


The driverWS is work space reserved for the MLID to use during packet 
processing. This field is 4 bytes in size. 


The protocolWS is work space reserved for IPX to use while processing 
the event associated with the ECB. This field is 8 bytes in size. 


The dataLen is the total length of the packet including the IPX header. 
This is the sum of the fragSzzes in the fragment list. 


The fragList consists of the fragCount and the fragAddress and fragSize 
of each fragment to be used as part of an IPX packet. This list is used by 
IPX to construct the packet. The count field is a word in size, the 
address field is 4 bytes in length and is in “selector:offset” format, and 
the size field is a word in size. All packets must have at least one 
fragment. The first fragment must always point the beginning of the IPX 
header and be at least 30 bytes in length. You determine how many 
fragments make up a packet. The fragmenting of the packet allows 
improved performance by avoiding a data copy until the packet is 
actually copied to the buffer on the LAN card. A packet guaranteed to 
cross all NetWare routers can be no larger than 576 bytes in total 
length, with 30 bytes for the header and 546 bytes remaining for data. If 
packets are only to be sent on the local net and will not be crossing 
routers, the maximum size is determined by the media size supported 
by the Multiple Link Interface Driver (MLID) and LAN card. The 
default number of fragments in the IPXCALLS.H include file is set to 2. 
You can customize the number of fragments according to the maximum 
number used in your application. 


IPX Header | 


The IPX Packet consists of two defined areas, the IPX header and the 
data. The IPX header is in high-low word format because the protocol 
was originally designed on machines where the word format is high- 
low. The IPX header consists of thirty bytes arranged in 6 fields, the 
Checksum, the Length, the Transport Control, the Packet Type, the 
Destination Address, and the Source Address. The IPX Header is illus- 
trated in Figure 24-5. 
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Figure 24-5, IPX 


Header (each square 
equals one byte). 


The Packet Checksum 


The Packet Length 


The Transport Control 


The Packet Type 


The Destination 
Address 


Checksum 

Length 

Transport Control 
Packet Type 
Destination Address 
Source Address 


The Checksum makes up the first 2 bytes of the header. Prior to 
NetWare SFT III, this field was not used to checksum the packet but to 
maintain conformity to the IDP (Internet Datagram Protocol) packet. 
When it is not being used to checksum the packet, it is set to OXFFFF by 
IPX. Starting with IPXODI.COM v2.0, this field is used for 
checksumming the packets for the NCP packet burst protocol and for 
SFT III support. 


The packet Length field is two bytes long and is the total length of the 
packet including the header. 


The Transport Control is set to 0x00 by IPX and is the number of hops 
the packet has taken. A hop is every time a network router is crossed. 
When this value reaches 16, the packet is discarded and no longer 
forwarded to other nets. 


The Packet Type is the XEROX defined type. For IPX, this value is 4. 
This field should be set to 4 by the application when sending packets. 


The Destination Address is 12 bytes long and is the internetwork 
address of the destination workstation plus the socket to de-multiplex 
on. This address is the Network, Node, and Socket of the process to be 
communicated with. This address must be set by the application when 
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The Source Address 


The data in an IPX packet 
is limited to 546 bytes for 
packets crossing routers, or 
to the media packet size 
minus the 30 byte header 
for local packets. 


sending packets. The network number is assigned by a network admin- 
istrator and is the logical address of the physical length of cable con- 
necting the workstation with the nearest router. A destination network 
of 0x00000000 means the local network. 


The node address of a workstation is either burned into the card being 
used as in Ethernet and Token Ring or is toggled on the card as in 
ARCNET. Anode address of 0xFFFFFFFFFFFF means the packet is a 
broadcast packet. A broadcast packet does not cross routers. To 
broadcast to a network other than the local network, the network 
number must be set to the network for which the broadcast is intended. 


The socket number is defined by the application and used to de-multi- 
plex communications. Sockets below 0x4000 are reserved for Novell 
internal use. Sockets from 0x4001 to 0x5000 are dynamically allocated. 
Sockets above 0x8000 are assigned by Novell to companies writing 
applications needing their own socket numbers. 


The Source Address is 12 bytes long and is the internetwork address of 
the workstation the application is running on. 


IPX Data 





The data in an IPX packet is limited to 546 bytes for packets crossing 
routers, or to the media packet size minus the 30 byte header for local 
packets. The data area structure and protocol are defined by the 
application. IPX uses the fragment descriptor list to locate the data to 
be placed in the packet. If the data is in one contiguous block of memory 
following the header, only one fragment would be necessary. However, 
allowing the multiple fragments permits the user to build a packet using 
non-contiguous locations in memory. 


The format of the packet and the protocol the application uses will 
depend on the actions that need to be taken or the requests that can be 
made. If an application only allows “read” access of a data base, then any 
request will only need to specify a record to read. There are many ways 
to specify this record, so many types of requests could be designed. 
Each one could be identified by a number in the first byte of data in the 
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IPX packet. The information following would be the data needed to 
perform the request and could be organized like the structure used in 
the application. The response packets could all have the same structure. 
They could be the fields of the record as defined in the database. 


In a distributed application with many requests and responses, the 
format of the packets can all include function numbers. The response 
number can use the same function number as the request. This would 
be an acknowledgment that the request had been received and was the 
type of the response being returned. 





SPX and Connections 


Being a connection-oriented protocol, SPX maintains a virtual connec- 
tion between two endpoints (one or more computers) and guarantees 
the delivery of packets in the same sequence that they are sent. This is 
accomplished through a series of timeouts and retries. When one end 
of an SPX connection sends a packet using SPX, the other end of the 
connection has a time out period within which to respond. After the 
time out period expires, SPX will resend a packet in an attempt to elicit 
an acknowledgement from the connection partner. If the total number 
of retries has been used and no acknowledgement has been received 
from the partner then the local SPX will abort the session and will clear 
it from the session table. The number of retries is set in the 
SpxEstablishConnection call or in the SpxListenForConnection call. If 
the retry parameter is set to zero, SPX will use the system default for the 
number of retries. The time out period between retries is configurable. 
The number of retries multiplied by the timeout value will be the total 
time that a session will stay alive without an acknowledgement. These 
two items, SPX Timeout and SPX Retry Count are configurable in the 
NET.CFG. Each connection has an optional connection watchdog. 
When the watchdog is enabled on a connection, SPX will send a packet 
every 30 seconds once the session has been inactive for ten minutes. 
This added security guarantees that the connection is in working order 
when the application attempts to use it once more. 





326 OS/2 and NetWare Programming: Using the NetWare Client API for C 





Figure 24-6. The SPX 
ECB Structure. 


The next and prev 
Fields 


The SPX Event Control Block 


As in IPX, SPX uses an event control block (ECB) for all communications 
with the NetWare SPX driver (Figure 24-6). You define your packet using 
the fragment list in the event control block. The fragment list specifies the 
locations in memory that are used to build a packet by concatenating them 
or to receive a packet by scattering the data to them. 


typedef struct 

{ 
VOID NWPTR fragAddress; 
USHORT fragSize; 

} SPAECEF Pag: 


typedef struct SPX_ECBStruct 

{ 
struct SPKUECBStruct NWPIR next; 
struct SPX_ECBStruct NWPTR prev: 


USHORT status: 
ULONG reserved; 
USHORT TPROTI Ds 
UCHAR pretilOle]: 
USHORT boardNumber; 
UCHAR immediateAddress[6]; 
UCHAR driverWS[4]; 
void NWPTR hsem; 
UCHAR protocolWS[4]; 
USHORT dataLen; 
USHORT fragCount; 
SPXECBFrag Treg lstizls 

} SPX_ECB; 


The next and prev fields are used internally by SPX to create a doubly 
linked list of ECBs. Each of these fields is a 16-bit far pointer. If the 
ECB is not in use by SPX, this field can be used by the application. The 
in use state of the ECB is indicated by the status field. 
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The status Field 


The reserved! Field 


The Socket 


The proflD Field 


The boardNumber Field 


The immediateAddress 
Field 


The status field indicates that the ECB is in use or not in use by SPX and 
the status of the event upon completion. A non-zero value for this flag 
indicates in use or an error condition. The errors for SPX all begin with 
OxA? in the high-order byte of the status field. No fields should by 
modified by the application while the ECB is in use by SPX. This field is 
a UINT16 field. For a detailed list of SPX completion codes, see the 
header file SPXERROR.H. 


The reserved] field is reserved for use by SPX. 


The Socket is the source socket to use for the connection. The socket is 
a de-multiplexing mechanism. The socket is a word in high-low order. 
The high-low order is necessary, because this the socket number SPX 
places in the packet header. The entire packet header is in high-low 
word order. The socket number could be compared to an apartment 
number in an addressing scheme. The network number is similar to 
the street, the node address to the building number. The socket 
functions much like an apartment number by further resolving the 
process to which the packet should be directed in the node, the way a 
letter is directed to an apartment in a building. 


The protlD field is the node address of the board specified by the board 
number. This node address is used by SPX along with the network 
number to create an internetwork address. 


The boardNumber field specifies which LSL board number to which 
SPX is bound that the application wishes to use to send or receive this 
packet. 


The immediateAddress field is set by SPX. The immediate address is 
the 6-byte node address of the nearest router that is aware of the 
destination address. The nearest router is assumed to be the first one 
to respond to the workstation when SPX calls IpxGetLocalTarget to send 
out the routing information broadcast. More about routing and routing 
broadcasts can be found in the “Service Advertising and Routing 
Theory” chapter. Unless its destination is on the local net, a packet is 
sent to the destination via the routing node that has information con- 
cerning the route to the destination. 
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The driverWS Field 


The hsem Field 


The protocolWS Field 


The datalen Field 


The fragCount and 
fraglist 





The driverWS is work space reserved for the MLID to use during packet 
processing. This field is 4 bytes in size. 


The hsem specifies the semaphore the application can block on until it is 
cleared by SPX. This allows the application to spawn a thread to monitor 
the progress of the ECB until the event it represents is completed. 


The protocolWS is work space reserved for SPX to use while processing 
the event associated with the ECB. This field is 8 bytes in size. 


The dataLen is the total length of the packet including the SPX header. 
This is the sum of the fragSzzes in the fragment list. 


The fragList consists of the fragCount and the fragAddress and fragSize 
of each fragment to be used as part of an SPX packet. This list is used by 
SPX to construct the packet. The count field is a word in size, the 
address field is 4 bytes in length and is in “selector:offset” format, and 
the size field is a word in size. All packets must have at least one 
fragment. The first fragment must always point to the beginning of the 
SPX header and be at least 42 bytes in length. You determine how many 
fragments make up a packet. The fragmenting of the packet allows 
improved performance by avoiding a data copy until the packet is 
actually copied to the buffer on the LAN card. A packet guaranteed to 
cross all NetWare routers can be no larger than 576 bytes in total 
length, (i.e. 42 bytes for the header and 534 bytes for data). If packets 
are only to be sent on the local net and will not be crossing routers, the 
maximum size is determined by the media size supported by the MLID 
and LAN Card. The default number of fragments in the SPXCALLS.H 
include file is set to 2. You can customize the number of fragments 
according to the maximum number used in your application. 


The Connection ID 





The connection ID from  SpxListenforConnection and 
SpxEstablishConnection is the local session ID. It is a relative offset for 
the entry in the session table. The connection ID returned in 
SpxEstablishConnection is a tentative value. This connection ID is not 
valid for communications until the ECB posted in the 
SpxEstablishConnection call completes with no error. 
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SPX Header | 


The SPX header is identical to the IPX header for the first 30 bytes. The 
next 12 bytes are used to sequence packets and to control the session. 
These twelve bytes are divided into 7 fields: 

e Connection Control, 

e Datastream Type, 

e Source Connection ID, 


e Destination Connection ID, 


e Sequence Number, 


Acknowledge Number, and 
e Allocation Number. 


These fields are illustrated in Figure 24-7. The Destination Network 
Address is only set by the application on an SPXEstablishConnection 
call. After the connection is established, SPX takes care of filling in all 
the fields in the SPX Header. The SPX packet type is five (5). 


The SPX packet type Checksum 
is five (5). Length 

Transport Control 

Packet Type 


Destination Address 
Source Address 
Connection Control 
DataStream Type 

Source Connection ID 
Destination Connection ID 
Sequence Number 
Acknowledge Number 


Figure 24-7. SPX Allocation Number 
Header (each square 
equals one byte). 
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Connection Control 


Datastream Type 


Source Connection ID 


Destination Connection 
ID 


Sequence Number 


Connection Control is one byte and is used for session maintenance. 
This field is used to indicate if the packet is a system packet (bit 7 set), 
an acknowledgement (bit 6 set), attention (bit 5 set), or an end of 
message (bit 4 set). These bit definitions are according to the SPP 
definition. Bits from 0 to 3 are undefined. An establish, terminate, or 
acknowledgement packet is a system packet. Acknowledgments in SPX 
are piggy-backed on the sends. This means that if a packet is received 
by one side of the connection and that side is about to send another 
packet, the acknowledgement bit will be set in the Connection Control 
field. This makes it possible to reduce traffic on the network by not 
requiring an individual acknowledgement for each packet. 


The Datastream Type is a one byte field used by SPX to flag the end of 
the session. When an application call SpxTerminateConnection, SPX 
sends a terminate packet with this field set to OxFE. In the 
acknowledgement to the termination packet, this field is set to OxFF. 
These values are managed by SPX. The only caution for the application 
is to reset this field to zero after the packet header is used with an ECB 
in SpxTerminateConnection. If the same header were used on a subse- 
quent send to another connection with this value still set in the header, 
that connection would be terminated as well. 


The Source Connection ID is the connection ID in the SPX located on the 
node specified as the source address in the packet. This connection 
identification is a relative offset into the connection table for the local SPX. 


The Destination Connection ID is the connection ID in the SPX located 
on the node specified as the destination address in the packet. 


The Sequence Number is the packet number that is being sent. This 
number is incremented by one for each packet sent on a connection. 
SPX guarantees that packets are delivered and processed in the se- 
quence they are sent. To do this, SPX keeps track of the sequence 
number and will drop any packet that arrives out of sequence. If the 
other end of the connection doesn’t receive an acknowledgement for 
the packet it sends, it will not send the next packet. SPX will continue to 
retry the send for which the acknowledgement is outstanding. 
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Acknowledge Number 


Allocation Number 


The Acknowledge Number is the sequence number of the remote SPX 
partner. Currently, SPX has a communication window size of one and is 
not a sparse acknowledgement protocol. This means that SPX requires 
can only send one packet before waiting for an acknowledgment and 
requires an acknowledgment for each and every packet it sends. 


The Allocation Number is the number of listens available at the time the 
packet was sent. When the allocation number equals the acknowledge 
number, the connection is in a standby state unable to receive any more 
packets until additional listen ECBs are available. SPX will continue to 
watch dog or maintain the connection until more listens are posted. 





Establishing SPX Connections 


An application can set the retry count to be used by SPX in the session 
before giving up on a packet. The default is 20 retries and this is used 
when the retry count is set to 0. This count is set in the 
SpxEstablishConnection and the SpxListenForConnection calls. The 
socket to be used for the connection is passed in to these calls as well. 


An additional level of session maintenance can be invoked using the 
watchdog flag. The watchdog is invoked by setting the watchdog flag to 
WATCHDOG_CONNECTION. The watchdog will periodically query 
the partner of an inactive connection to verify the connection is still 
alive. 


Fields in the ECB that you need to initialize before calling 
SpxEstablishConnection include hsem, fragCount, and fragList. Addi- 
tionally, you need to set the destination address in the SPX header. 


Before calling SpxListenForConnection, you need to initialize the follow- 
ing ECB fields: hsem, fragCount, and fragList. If several connection 
requests may be received simultaneously, then the application should 
post several listens for connection to reserve sufficient space in the SPX 
connection table for the expected number of connections. 
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SPX Processing 


ECBs are processed in the queue in whatever order they happen to be. 
No order should be assumed and all ECBs should describe packets 
large enough to receive the largest packet that will be sent on the 
socket. 


When an application will be processing a high rate of SPX transmis- 
sions, the pool of outstanding listens should be large enough to allow 
for processing time during which the ECBs will be still in use. The 
number of ECBs that would allow for this processing lag would be ona 
connection basis. As arule of thumb, between five and 15 listen ECBs is 
the most efficient range for a pool of connection ECBs with current 
packet transmission speeds. 


Terminating SPX Connections 





Two ways exist to tear down an SPX connection. These two methods 
are SpxTerminateConnection and SpxAbortConnection. To properly ter- 
minate a connection when communications are complete, an 
SpxTerminateConnection should be used. The SpxTerminateConnection 
sends packets to the partner in the SPX connection to inform of the 
pending termination. This allows the remote partner to clean up its 
session tables and free up resources. The remote node in a connection 
will send the initiator an acknowledgment that the termination request 
was received and processed. At that point, both nodes remove the 
connection from their tables and the connection has been terminated 
gracefully. The ECB fields used in the SpxTerminateConnection call 
include the hsem, the fragment count, and the fragment list. 


An SpxAbortConnection should only be used when the communication 
or the application is in an unrecoverable state. The abort connection 
does not attempt to communicate with the remote partner in the con- 
nection, but only removes the connection from the connection table and 
frees up local resources. 
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sStatus 


Figure 24-8. 
SPX_SESSION 
Structure. 


SPX Connection Information 


The SpxGetConnectionInformation call can provide the application with 
useful information concerning the connections currently in the local 
connection table. The SPX_SESSION structure is defined in the 
SPXCALLS.H header file as in Figure 24-8. 


typedef struct SPX_ConnStruct 


UCHAR sStacus: 

UCHAR SFlags; 

USHORT sSourceConnectID; {* lo-hi */ 
USHORT sDestConnectlID; /* lo-hi */ 
USHORT sSequenceNumber ; fe Orn Fe 
USHORT sAckNumber; {® lo-fi */ 
USHORT SAllocNumber; /* lo=hi */ 
USHORT sRemoteSequenceNumber ; Pe Lonny = y 
USHORT sRemoteAckNumber ; /® |o-hi */ 
USHORT sRemoteAllocNumber; #*® lo-fi */ 
USHORT SLPYOELD: f*® lo-fi *¥ 
UCHAR sProtlDL6): /* hielo */ 
USHORT sBoardNumber; /* lo-hni */ 
UCHAR sImmediateAddress[6]; f* hiela *7 
ULONG sRemoteNet; /* hi=lo */ 
UCHAR sRemoteNode[6]; J* Hhi-1o *7 
USHORT sRemoteSocket; ce Filo *¥ 
USHORT sRetryCount; /*® la-hi */ 
ULONG sRoundTripTimer; Ce Los ee 
USHORT sRetransmitCount; P® lo-"i 7 


fr SPAOSESSION: 


The sStatus field indicates if the connection is listening for a connec- 
tion, has sent an establish connection packet, is active, or has sent a 
terminate connection packet. 
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sFlags 


Connection Ids 


Connection Packet 
Numbers 


The Sflags field maintains information as to whether or not the connec- 
tion is being watchdogged. If the connection is watchdogged, the flags 
are non-zero. 


Each connection maintains the source connection ID and the destina- 
tion connection ID. This information can be queried using NetWare 
Diagnostics. Using the destination connection ID, a packet can also be 
sent to the connection partner and connection information retrieved 
from that endpoint as well. 


The sSourceConnectID is the connection ID for the local side of the SPX 
connection. 


The sDestConnectID is the connection ID for the remote side of the SPX 
connection. 


The numbers used in the packet to sequence the SPX packets are 
maintained for both ends of the connection. This enables SPX to easily 
acknowledge packets from the connection partner and to know whether 
the remote endpoint can possibly receive a packet (according to the 
remote allocation number). 


The sSequenceNumber field is the local sequence number for the SPX 
connection. 


The sAckNumber field is the local acknowledge number for the speci- 
fied SPX connection. 


The sAllocNumber field is the local allocation number for the specified 
SPX connection. 


The sRemoteSequenceNumber is the sequence number of the remote 
partner of the SPX connection. This field’s value should be the same or 
near to the value of the local acknowledge number. 


The sRemoteAckNumber is the acknowledge number of the remote 


partner. This number corresponds to the local sequence number and 
should be equal or near to it. 
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The sRemoteAllocNumber is the allocation number that the remote 
partner of the SPX connection. This number corresponds to the num- 
ber of listens posted minus the local sequence number, which is the 
total number of listens outstanding on a socket. Because the socket is 
used as a de-multiplexing mechanism, it is recommended that only one 
connection be established per socket. 


Packet Transmission This set of information is maintained by SPX to be set in the SPX header 


2 of all packets that are transmitted, including system packets and 
' Connection ECB acknowledgements, or in the ECBs before they are submitted to IPX. 
htormation These fields include the sZProtID, sProtID, sBoardNumber, 


slmmediateAddress, sRemoteNet, sRemoteNode, and sRemoteSocket. 


Session Statistics The sRetransmitCount is the number of times that SPX has to resend a 
packet for the connection specified before the destination is considered 
unreachable. SPX will resend a packet any time it doesn’t receive an 
acknowledgement within the time specified by the retry timeout in the 
NET.CFG. There are three reasons a packet may be resent by SPX, all 
of these reasons are indicated by the lack of an acknowledgment to the 
original transmission and are illustrated in Figure 24-9. 


1. A packet doesn't reach 
the remote workstaton 


2. An acknowlegement doesn't reach 
the local workstation 





[| | | | 3. An acknowledgement isn't received 
no listens are outstanding. 





Figure 24-9. Failure 
Scenarios for SPX 
packets. 
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The sRoundTrip Timer is the amount of time necessary for a packet to be 
sent to the remote workstation and an acknowledgment to return. 


The sRetryCount is the value set when the connection was established 
that SPX uses for the total number of packet retries. 


IPX, SPX, and 0S/2 





In order to use IPX under OS/2, you need the most current 
IPXCALLS.DLL. To use SPX, you need the most current 
SPXCALLS.DLL In the next chapter, we explore the details for pro- 
gramming IPX and SPX programs in OS/2. The application has been 
implemented to use IPX and SPX interchangeably. 
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Come, come, no more of this unprofitable chat. 


—William Shakespeare, King Henry IV Part 1 
Programming a distributed application using IPX and SPX can seem 
threatening because of the work involved in defining the communica- 
tions between the endpoints of the application. With the interface and 
explanations in this chapter, you will find that it is really quite easy to 
use IPX and SPX to communicate between two nodes on the network. 
The interface provided as a simplification for communications program- 
ming is a C++ class, Conn. This class has four methods: 
Conn, the constructor, 
~Conn, the destructor, 


Send, the packet send function, and 


Receive, the data retrieval function. 
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For more information on C++ programming, you should read the manu- 
als that come with your compiler. The sample code is also a good 
resource for the specific way to use the Conn class. 


Node to Node Basics 





To communicate between two nodes on the network, you will need a 
method for determining the internetwork addresses of the two end- 
points. The local endpoint address is easy to determine, you call the 
function [pxGetInternetworkAddress. This will return the four byte logi- 
cal network number for the network segment your machine is con- 
nected to and the six byte physical node number of the LAN card in 
your machine. Add to this the two byte socket number that you want to 
use for you application. You now have your local 12 byte internetwork 
address. 


Finding the address of the remote endpoint requires a little more work. 
Typically, the client end of the distributed process searches for the 
service provider end of the distributed process. If the service provider 
is broadcasting its presence by using SAP, then the client can scan a 
bindery or use SAP queries to discover the address of the service 
provider. Otherwise, the application needs to be instrumented with a 
custom location method. For example, one location method can use 
IPX broadcasts on the network with all nodes running the application 
listening for and responding to these broadcasts. Once both addresses 
are known, the application goes through steps to initialize the IPX and 
SPX drivers and the event control blocks (ECBs). 


Set up for Using IPX and SPX 





The code in Figure 25-1 shows the steps an application needs to take to 
begin using IPX and SPX services. As demonstrated in this code, you 
need to take two main steps before using IPX or SPX calls. First, you 
need to find out your address. You do this by making the call to 
IpxGetInternetworkAddress. You are returned your 10 byte 
“network:node” address as we discussed earlier. 
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Conn::Conn( UINTS8 *target, UINT16 *sendSocket, UINT16 
*receiveSocket, 
UINT32 *status, UINT32 flag) 


{ 
UINT16 rcode, ccode; 


connFlag = flags = flag; 

connFlag &= SPX_OBJ; 

memcpy(&targetNodeLO], target, 10); 

if (0 != (rcode = IpxGetInternetworkAddress(myAddr) ) ) 
goto done; 

sSocket = *sendSocket; 

rSocket = *receiveSocket; 

if (connFlag) 


rcode = IpxOpenSocket(&rSocket) ; 
if (!rcode) 
memcpy(&targetNode[10], &sSocket, 2); 
} 
done: 
*status = (UINT32)rcode; 
return: 


Figure 25-1. Setting 
up to Use IPX and 
SPX. 


Next, you need to open the socket you are going to use for 
communications. This socket should be opened with [pxOpenSocket if 
you are going to use IPX services or with SpxOpenSocket if you are 
going to use SPX services. You pass the address of the socket variable 
in to the open socket calls. If your socket value is set to 0x0000, then 
you will be assigned a dynamic socket and the socket number will be 
returned to you in this variable. 
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Figure 25-2. Creating 
Connections with 
SPX—Establish 


Connection. 





Creating Connections in SPX 





To send and receive packets using SPX, you need to take an additional 
step after opening the socket. You need to create an SPX connection. 
Two methods, as shown in Figures 25-2 and 25-3, exist for creating SPX 
connections: SpxEstablishConnection and SpxListenForConnection. 
SpxEstablishConnection is an active call to a remote node with a request 
to establish an SPX connection. On the other hand, 
SpxListenForConnection is a passive call that waits for a remote connec- 
tion to request a connection. In typical client/server distributed appli- 
cations, the SpxListenForConnection is used by the server and the 
SpxEstablishConnection is used by the client. 


connECB.fragCount = 1; 
connECB.dataLen = sizeof(SPX_HEADER) ; 
connECB.fragListL0O].fragAddress = (void NWPTR)&connHdr ; 
connECB.fragListL0].fragSize = sizeof (SPX_HEADER) ; 
listenECB.fragCount = 2; 
listenECB.dataLen = sizeof(SPX_HEADER)+PACKET_SIZE; 
JistenECB.fragListL0O].fragAddress = (void NWPTR)&listenHdr; 
listenECB.fragListL0O].fragSize = sizeof(SPX_HEADER) ; 
JistenECB.fragListLl].fragAddress = (void 
NWPTR)&dataBufLNUM_ECBS]; 

listenECB.fragListll].fragSize = PACKET_SIZE;: 
rcode = SpxOpenSocket((UINT16 NWPTR)&rSocket) ; 
if (!rcode) 

memcpy(&targetNodeL10], &sSocket, 2); 
else 

goto done; 
if (flags & SPX_LISTENER) 


SpxListenForConnection2(rSocket, &connECB, 
&listenECB, 0, 
WATCHDOG_CONNECTION, &conn); 


else 


memcpy(&connHdr.destNet, targetNode, 12); 

ccode = SpxEstablishConnection2(sSocket, &connECB, 
&listenECB, 0, 
WATCHDOG_CONNECTION, &conn) ; 
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Figure 25-3. Creating 
Connections with 
SPX—Listen For 

Connection. 





To use SpxEstablishConnection (Figure 25-2), you need to set up two 
ECBs, the connection ECB and the listen ECB. Each of these ECBs 
requires the fragCount and fragList fields to be set. The hSem field also 
needs to be set if you are using system or RAM semaphores. To learn 
more about these semaphores, you will need to use other OS/2 pro- 
gramming resources. The connection ECB is used to create and send 
the connection request packet. The listen ECB is used to receive the 
connection response from the remote partner. The confirmation packet 
sent in reply to the connection request will include the connection 
number assigned at the remote end and connection control informa- 
tion. The packet fragments should consist of one 42-byte header with 
the destination address set in the header pointed to by the connection 
ECB. This tells SPX which node to send the connection request to. 


connECB.fragCount = 1; 
connECB.dataLen = sizeof(SPX_HEADER) ; 
connECB.fragListL0].fragAddress = (void NWPTR)&connkdr; 
connECB.fragListL0].fragSize = sizeof(SPX_HEADER) ; 
listenECB.fragCount = 2; 
listenECB.dataLen = sizeof(SPX_HEADER)+PACKET_SIZE; 
listenECB.fragListL0O].fragAddress = (void NWPTR)&listenHdr; 
listenECB.fragListl0O].fragSize = sizeof(SPX_HEADER) ; 
listenECB.fragListLl].fragAddress = 

(void NWPTR)&dataBuf[NUM_ECBS]; 
listenECB.fragListLl].fragSize = PACKET_SIZE; 
rcode = SpxOpenSocket((UINT16 NWPTR)&rSocket) ; 
if (!rcode) 

memcpy (&targetNodeL10], &sSocket, 2); 
else 

goto done; 
if (flags & SPX_LISTENER) 
{ 

SpxListenForConnection2(rSocket, &connECB, 

&listenECB, 
0, WATCHDOG_CONNECTION, &conn); 


An IPX or SPX Protocol-based Service Provider 343 





Along with these ECBs, you pass in the socket to use, the number of 
retries, flags, and a variable to receive the connection number assigned 
by the SPX driver. The driver will set the source address in your packet 
using the “network:node” number for your machine and the socket 
number you pass in. The number of retries defaults to the value set by 
the user in the NET.CFG. Ifyou pass in zero for the number of retries, 
the SPX driver uses this default. Otherwise, it will use the value you 
specify. The flags that you pass in currently have only two valid values, 
0 and WATCHDOG_CONNECTION. When you _ choose 
WATCHDOG_CONNECTION, the SPX driver will send a periodic 
tickle packets to the remote partner any time the connection is inactive 
for more than two seconds. 





The SpxEstablishConnection function will return right away with the 
connection number reserved for the connection in the connection vari- 
able. When the semaphore in the ECB is cleared and the status indi- 
cates success, the connection number is valid and can be used. If the 
connection could not be established, the status field will be non-zero 
and the connection number is not valid. ECB status field values above 
OxA000 are errors. You can wait for the establish connection ECB to 
complete by checking for the status field to be equal to 0x3000 
(SPX_SUCCESSFUL) or above 0xA000 in a WHILE loop. 


Using SpxListenForConnection (Figure 25-3), requires only one ECB to 
be initialized, the listen ECB. The same fields in the ECB must be 
initialized, but no fields in the packet header pointed to by the fragment 
list need to be set. This call also takes the socket, retries, flags, and 
connection variables. The socket you use tells the SPX driver which 
socket the connection request is expected on. The retries, flags, and 
connection variables serve identical purposes to those performed in the 
SpxEstablishConnection call. 





Sending and Receiving Packets © 


Once your connection is established for SPX communications or you 
have opened an IPX socket, you can send and receive packets. The 
process differs slightly for sending IPX and SPX packets, as is shown in 
Figures 25-4 and 25-5. To send a packet with IPX or SPX, you need to 
set the fragment count and fragment list in the ECB. For SPX, you may 
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Figure 25-4. Sending 
Packets over IPX. 


Figure 25-5. Sending 
Packets Over SPX. 


also want to set the hsem field. For IPX, you need to set the destination 
address in the packet header. Then, to send a packet, you call 
IpxSendPacket for IPX packets and SpxSendSequencedPacket for SPX 
packets. IpxSendPacket requires the socket and the ECB. 
SpxSendSequencedPacket requires the connection number and the ECB. 


1px(Ol] .<Trdglount = 2% 

ipxLO].dataLen = PACKET_SIZE; 
ipxlO].fragListLO].fragAddress = (void NWPTR)&ipxHdrLO]; 
ipxLO].fragList[0].fragSize = sizeof(IPX_HEADER); 
ipxLO].fragListLl].fragAddress = (void NWPTR)data; 

1PX(O)] .Fraglistlii.tfragsize = datesize: 

memcpy((UINT8 NWPTR)&(ipxHdrLOJ].destNet), targetNode, 12); 
IpxSend(rSocket, &ipxL0]); 

copoage = SUCCESSFUL: 


connECB.fragCount = 2; 
connECB.dataLen = PACKET_SIZE; 
connECB.fragListLO].fragAddress = (void NWPTR)&connHdr; 
connECB.fragListL0O].fragSize = sizeof (SPX_HEADER) ; 
connECB.fragListL1].fragAddress = (void NWPTR)data; 
connECB.fragListL1].fragSize = dataSize; 
SpxSendSequencedPacket(conn, &connECB) ; 
while((connECB.status < OxAQ001) && 
(connECB.status != SPX_SUCCESSFUL) ) 

{ 

ccode=ccode; 
} 
if (connECB.status == SPX_SUCCESSFUL) 

Ecode = SUCCESSFUL: 
else 

ccode = connECB.status; 


Receiving packets is less similar between IPX and SPX applications 
(Figures 25-6 and 25-7). To receive a packet using IPX, you set the 
fragCount and fragList fields in the ECB and then call [pxReceivePacket 
with the socket the packet should be coming in on, the timeout value 
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before giving up on the receive, and the ECB. The timeout value is in 
milliseconds. The IPX driver will try to get a packet from the LSL hold 
queue. If there isn’t a packet, then IPX will keep trying until the timeout 
expires. 


ipSLli.fragGount — 2: 

jpxLlJ].dataLen = PACKET_SIZE; 
ipxLl].fragListLO].fragAddress = (void NWPTR)&ipxHdrL1l]; 
ipxllJ.fragListl0O].fragSize = sizeof(IPX_HEADER) ; 
ipxLl].fragListLl].fragAddress = (void NWPTR)data; 
ipxLlj.fragList{il.fragsize = datasize: 

ccode = IpxReceive(rSocket, time, &ipxLl1l]); 


Figure 25-6. 
Receiving Packets 
with IPX. 


To receive a packet using SPX, you set the fragCount, fragList, and 
dataLen, fields in the ECB and then call SpxListenForConnectionPacket. 
This call requires only the connection number and the ECB to receive 
any packets coming in on the connection specified. Multiple listens for 
packet can be posted for a connection to receive data as it comes in. 
With these ECBs and packet buffers available to SPX on demand, SPX 
can perform more efficiently. Packets have been received by the 
application when the ECB hsem semaphore is cleared or the status field 
has changed to 0x3000 or a value above 0xA000. 
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Figure 25-7. 
Receiving Packets 
with SPX. 


if (flags & SPX_OBJ) 
{ 
if €1lIiStenECR.status = SPX SUCCESSFUL) 
{ 
memcpy(data, &dataBuf[NUM_ECBS][0], 
dataSize); 
SpxListenForConnectionPacket(conn, 
&listenECB); 
ecode = SUCCESSFUL: 
} 
else if (listenECB.status > OxA000) 
ccode = listenECB.status; 
else 
ccode = NO_DATA; 


Service Providers: An Example — 





The example code for this chapter, from which the figures have been 
taken, includes a simplified interface to the IPX and SPX services in 
CONN.CPP. The rest of the example demonstrates how to create a 
distributed make process using IPX or SPX to communicate between 
the two nodes. 


Figure 25-8 shows the code for the server end of the distributed pro- 
cess. This code is in MAKESVR.C. To create the server takes five steps: 
initialize IPX or SPX, begin advertising the service, process requests, 
shutdown advertising, and deinitializing IPX or SPX. The first, second, 
fourth, and fifth steps have been discussed in this chapter and are also 
covered in the Service Advertising Protocol (SAP) chapters later in this 
book. The step we will focus on here is the third step, process requests. 
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/f Set up to use IPX or SPX 
UINT8 targetlL12Z]) = {0xd0,0x00,0x00, 0x00, \ 


UxXPrF,OXFEF,QxFF,OXFF,UxFF <OxFF, * 
Ox55,0x%55}: 
UINT16 sSocket = 0x5555, rSocket=MAKE_SOCKET; 
VUINTS2 status: 
Conn myConn(target, &sSocket, &rSocket, &status, 
SPX_OBJ | SPX_LISTENER); 
UINT16 rc; 
SAP_INFO SaplInfo; 


// We are listening, so we don’t care what the target is. 
if {status) 
{ 
BPINGCELTEPrOr TNIGializing conn objects: Oxex” TC): 
myConn. Conn: Conn): 
return 0; 


Strcpy(sapInfo.serviceName, “MAKE_SERVER”) ; 
SapInfo.servicelype = MAKE_SERVER; 
sapInfo.serviceSocket = MAKE_SOCKET; 
AdvertiseService(&sapInfo); 
ProcessRequests(myConn) ; 
ShutdownSap(&sapInfo); 


myConn.Conn::~Conn(); 
return 0; 


void ProcessRequests(Conn& myConn) 


UINTI6G re: 

ThreadData tData; 
RequestData reqData; 
ReplyData repData; 
int threadID; 

void (*myThread)(void *); 


myThread = (void(*)(void *))RunRequest; 


while (!kbhit()) 


Figure 25-8. Make 


Server Sample Code. 
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Figure 25-8. Make 
Server Sample Code. 
(Continued) 


i & 


myConn.Conn::Receive((UINT8 *)&reqData, 
sizeof(RequestData)); 


1f L3G) 


{ 


tData.connObj = &myConn; 
tData.rp = &repData; 
Switch (reqData.requestType) 
{ 
case MAKEIT_COMPILE: 
SOriner(ccomline, “bee =-€ 25 23", 
reqData.options, 
reqData.sourcePath) ; 
_beginthread(myThread, 8096, 
&tData); 
break; 
case MAKEIT_LINK: 
Sprintf(comLine, “bcc 4s 4s”, 
reqData.options, 
reqData.sourcePath) ; 
_beginthread(myThread, 8096, 
&tData); 
break; 
case MAKEIT_MAKE: 
Sprintf(comLine, “make 4S 4s”, 
reqData.options, 
reqData.sourcePath) ; 
_beginthread(myThread, 8096, 
&tData); 
break; 
default: 
break; 


else if (re != NO_DATA) 


break; 


void RunRequest(ThreadData *tData) 


This is the call to make to execute the request. 
System(comLine) ; 
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tData->rp->cCode = 0; 
tData->connObj->Conn::Send((UINT8 *)tData->rp, 
sizeof(ReplyData)); 


_endthread(); 
Figure 25-8. Make 
Server Sample Code. 
(Continued) 


To process requests, you have to get data back and forth across the 
network, interpret it properly, and take the appropriate action. How you 
do these things will affect the design and implementation of your 
application. 


Moving data back and forth on the network requires packet structure (s) 
to be defined. The packet structures in Figure 25-9 were used by the 
make server and client to communicate the action desired and the 
completion state. The request packet contains all the information 
necessary for the make server to take the action specified in the 
requestType field of the request packet. The requestType uses 0 to 
indicate a compile, 1 to indicate a link, and 2 to indicate a make. The file 
to be used is indicated by the source path and the command line options 
are specified by the options field. The client calls conn::Send with a 
pointer to a request structure and the size of the structure. The request 
structure will be used as the data portion of the packet sent to the 
server. 


typedef _RequestData_ 

{ 
UINT8 requestType; /* Q=compile, l=link, 2=make */ 
UINT8 sourcePath[256]; 
UINT8 options[80]; 

} RequestData; 


typedef _ReplyData_ 
{ 


UINTS8 cCode; 
} ReplyData; 
Figure 25-9. Packet 
Structures for Make 
Service Requests and 
Replies. 
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The server receives the packet by calling conn::Receive. The receive 
data is copied to the pointer specified by the server. The server checks 
the rvequestType and then processes the request accordingly. The server 
constantly checks to see if there are any requests to be processed. This 
process allows the user to continue to use the client machine while the 
files are being built at another machine. 


Distributed applications built on IPX and SPX services can allow mul- 
tiple users to share the same resources and to continue working while 
the background processing occurs. IPX and SPX applications can 
operate completely independent of the presence or absence of NetWare 
servers. 
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“Did he not advertise?” 

“No.” 

“Then, what clue could you have as to his identity?” 
“Only as much as we can deduce.” 


—Arthur Conan Doyle, Blue Carbuncle 


When writing any type of distributed application, you want to under- 
stand the capabilities of Service Advertising Protocol (SAP) and Rout- 
ing Information Protocol (RIP) on the network. These two protocols are 
used by NetWare servers to advertise their services to clients and to 
communicate routing changes throughout the network as well as by 
NetWare clients to find services available on servers. These protocols 
can serve as a network information courier for your applications to 
locate whatever they need on the network. Let’s discuss how SAP and 
RIP work and how you can take advantage of them. 
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All NetWare servers listen 
for these periodic 
identification broadcasts to 
build a list of available 


servers and their locations. 











Service Advertising Protocol 


SAP is built on Internetwork Packet Exchange (IPX). Using IPX, SAP 
broadcasts identify the type and location of a service provider. Novell 
services use SAP to periodically identify themselves on the network. 
The SAP protocol requires that all services using SAP send an advertis- 
ing broadcast packet every 60 seconds. These packets continue until 
the service process terminates by sending a shut down packet or until 
the process terminates ungracefully. All NetWare servers listen for 
these periodic identification broadcasts to build a list of available serv- 
ers and their locations. The real power available here comes from what 
the servers do next. Once a server has discovered new services 
advertising on the network, it passes that information on to the other 
NetWare servers on the network when it does its own periodic SAP 
broadcasts. So, with just one packet every 60 seconds, the entire 
internet can discover your application is ready for business. 


In the periodic broadcasts an application makes, the service type as- 
signed to it from Novell and the address are provided to identify and 
locate the application. The service provider type is a numeric value that 
identifies the service being provided. It is also referred to as the 
bindery object type. You can call Novell and reserve a service type for 
your server. A partial list of service types can be found in Figure 8-4 in 
the Bindery Services Theory chapter in this book. 


The location of the service provider is the internetwork address (includ- 
ing the socket) that the service provider expects to be contacted on. 
This socket can be a dynamic socket or a well-known socket. A dynamic 
socket is one which is dynamically assigned by the IPX drivers when 
you make an open socket call with ussocket set to 0. A well-known 
socket is one which you have reserved through Novell’s developer 
relations or one which is well-known on the network for its standard 
use. Well-known sockets and their purpose can be found in Figure 26-1. 
Typically the socket in the advertised internetwork address can be used 
in one of two ways: the socket is used for all incoming traffic to the 
service provider and the service provider manages to sort out all the 
requests using connection numbers or client addresses, or the socket is 
used for incoming requests to connect and potential clients are given a 
dedicated socket to call back on. The NetWare server uses the first 
method with socket 0x0451 (high-low) advertised for all incoming traf- 
fic to use for connecting. NetWare Diagnostic services uses the second 
method. 
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Figure 26-1. Well- 
known Sockets. 


The SAP information is 
aged over a 90 second 
interval. 





Socket 


0x0452 SAP socket 
0x0453 RIP socket 


0x0454 NetBIOS socket 


0x0456 Diagnostics socket 








A NetWare router or file server listens for broadcasts from other serv- 
ers on socket 0x0452 (high-low). The SAP broadcasts are picked up by 
NetWare routers and stored in the local name data base (the bindery or 
the directory) as dynamic objects on servers and in the server table (in 
the routing component). The server table and its function for routing 
information are discussed later in this chapter in the “Router Informa- 
tion Protocol” section. Every 60 seconds, each file server advertises 
itself and six other servers in each server broadcast packet. Any 
application listening on socket 0x0452 must supply listen packet buffers 
large enough to receive the largest service broadcast packets coming 
from the NetWare servers. 


In order for servers to know when other services have disappeared and 
when they need to be removed from the name tables and server routing 
tables, the SAP information is aged over a 90 second interval. So, if the 
router/server doesn’t receive another SAP packet about a particular 
service within 90 seconds, the information for the service provider in 
question is deleted. Whenever a server deletes a service from its server 
name table, it sends a shutdown broadcast to the networks it is con- 
nected to. This tells all the other routers connected that packets can’t 
be routed to the deleted service through the server notifying them of 
the deletion. Another way the SAP information for a particular service 
provider can be removed from the router/server tables is for the ser- 
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Finding Services 


vice provider to send a shutdown packet. A good service should 
generate the service shutdown packet before shutting down gracefully. 
Receipt of this packet also generates a shutdown broadcast the router/ 
server to the networks of which it is aware. 


All of the services on the network can be located by the client side of the 
distributed application by querying the NetWare routers. Once a ser- 
vice provider can be located by a client application, a connection can be 
built and services provided. 


Your application can find its service providers in one of several ways, 
some are only available in NetWare 4.x and some are available on all 
NetWare systems. An application can do any of the following: 


Listening on the SAP socket (0x5204), 

Scanning the bindery for the service provider object, 

Scanning the Netware Directory for the service provider object, and 
Making a SAP request. 


You can only listen on the SAP socket if no other application on your 
workstation (or on the node in question) has previously opened it. This 
method is the least efficient method for finding a service provider, but 
has the advantage of being based on IPX and thus independent of the 
presence and state of the NetWare servers. To listen on the SAP socket, 
first you open it, using IpxOpenSocket. Next, you use [pxReceive to 
receive SAP packets. The ECBs you pass to JpxReceive must have 
packet buffers at least 480 bytes in size to receive NetWare server 
packets without errors. Using this method, your application needs to 
keep a table of the type of service providers it uses and age it appropri- 
ately. 


Scanning the bindery for the service provider object and retrieving its 
address is a relatively simple function that requires the service type, 
which is the same as the bindery object type, and/or the service name. 
This method is supported on NetWare networks composed of NetWare 
2.x servers, NetWare 3.x servers, and NetWare 4.x servers running 
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Get Nearest Service 
Queries 


bindery emulation. The service provider address is found in the 
NETWORK_ADDRESS property of the service provider object. Infor- 
mation on how to find an object in the bindery and how to read its 
properties is found in the two bindery chapters earlier in this book. 


Scanning the NetWare Directory for the service provider object and 
retrieving its address is more complex than scanning the bindery, and 
is only possible on NetWare 4.x servers. This method requires know- 
ing the base object class of the service provider object. Instructions on 
how to find objects and their attributes can be found in the two NetWare 
Directory Services chapters earlier in this book. 


Making SAP requests is simply a matter of sending IPX packets. SAP is 
not dependent on NetWare servers, but is dependent on either routers 
available to fulfill the requests or on service providers set up to listen for 
SAP query broadcasts and to respond to them. The service provider can 
only listen for SAP queries if no other software component on the 
workstation has previously opened the SAP socket. 


Two kinds of SAP requests exist and can be used by your application to 
find the services it needs on the network. These requests are the “Get 
Nearest Service” query and the “Get General Service” query. 


In the “Get Nearest Service” query, all NetWare routers on the local net 
respond with the server name of the type requested that is closest in 
terms of hops and transport time. The client assumes that the first 
server that responds to this query is also the closest server to the client. 
For example, a client on network FADE2300 sends a packet requesting 
information as to the whereabouts of a server of type 180. Figure 26-2 
illustrates making a SAP request for the “Get Nearest Service” query. 
The NetWare file server knows of two file servers of type 180: one on 
network ECB1111 and one on network FADE0000. The client making 
the request is on network FADE0000, so the file server returns the 
address of the server on network FADE0000. 
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NetWare 
File Server 


FADE0000 


Ps Get Nearest Server [ Type 180 ] 


Server 
Type 180 
Figure 26-2. Get 
Nearest Server Query. 


Get General Service A “Get General Service” query by the same workstation in Figure 26-2 

Queries for all servers of type 180 would generate a response from the file server 
listing both servers and their respective addresses. When you send a 
“Get General Service” query packet, you need to be prepared to receive 
several response packets for the information requested or be aware that 
many responses are being ignored. Server name lists can be created 
using the responses to the “Get General Service” query without a 
workstation creating an attachment to any particular server. 


Router Information Protocol 





Router information protocol (RIP) works in a similar fashion to SAP, but 
does not typically have many interfaces exposed. RIP is one of the 
protocol NetWare routers use to inform other NetWare routers about 
which networks exist and how to get to them. NetWare routers use a 
dynamic routing algorithm to route packets on the network. This 
algorithm requires that each router not only know about all accessible 
destination network numbers, but also about all the routers that are one 
hop away that can route packets toward those networks. Routers direct 
packets to other routers based on the smallest transport time and how 
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Figure 26-3. Routing 
on an Internetwork. 


many packets are currently queued up to be sent on to that node. A 
“slow” network will only be used for routing packets if it is the only 
route available to the network. Routing on slow networks only when 
necessary, routers help prevent slow connections—like modem 
connections—from being used to route packets to networks that are 
also connected to each other by Ethernet or some other lower cost, 
higher speed link. 


The only interface to a RIP service exposed to you, as an application 
developer, is IpxGetLocalTarget. IpxGetLocalTarget sends a “Get Near- 
est Router” RIP packet. This packet contains the destination address for 
which you need a route. The RIP response packet contains your original 
destination address, the node address for the nearest router, and the 
estimated round trip time for a packet to get to the destination. 


In the example in Figure 26-3, the networks 01010101, ECB, 
FADE2300, and 02020202 are interconnected. Any server in this 
internetwork example will have at least two routes to any other net- 
work. If a packet was to be sent from the network 02020202 to the 
network ECB, the NetWare routers would know that routes existed 
from 02020202 directly to ECB with a distance of two hops, through 
FADE2300 with a distance of three hops, and through 01010101 with a 
distance of four hops. The packet will be routed directly through a 
server with a connection to ECB unless there are more packets waiting 
to be sent to that node with a total transport time greater than that of 
going indirectly through FADE2300. 


01010101 


FADE2300} © 
Le 










02020202 
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‘I will not announce thee unless thou tellest my name.” 


—Egyptian Book of the Dead 


In this chapter we’ll discuss how to write code that will advertise your 
service during the life of your application and shut down your advertis- 
ing when required. This sample code is available on the disk provided 
with this book. Using this code, you can advertise any service on the 
network without blocking your main application processing. This appli- 
cation is very simple. A description of the program and the assumptions 
we made in order to simplify this example are listed in Figure 27-1. 
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PROGRAM: SAP.EXE 


DESCRIPTION: Spawns a thread that does a SAP broadcast 
every 60 seconds. 


SYNTAX: SAP 


REMARKS: SAP advertises a job server type to any 
clients that want to take advantage of it. 
It uses socket 0x8456. 


SIMPLIFYING 
ASSUMPTIONS: e All setup and tear down occurs in the 
main() function of the program. 


« No real processing is done by the 
Sample, but any processing to be done 
(other than setup) would occur after the 
call to AdvertiseService and before the 
call to ShutdownSAP. 
Figure 27-1. 
Simplifying 
Assumptions for the 
SAP Programming 
Sample. 


Service Advertising and Shutdown: 





An Implementation 


The application consists of four functions: main, AdvertiseService, 
Sapper, and ShutdownSAP. ‘The prototypes for these functions are 
found in Figure 27-2. The code requires several steps to be taken in 
order to properly communicate to the IPKCALLS.DLL. These steps set 
up the application to “thunk,” or to pass 16-bit “selector:offset” ad- 
dresses when required. During the discussion of each function, we will 
highlight the information necessary for good NetWare SDK program- 
ming practices. 
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Figure 27-2. 
Prototypes for Sample 
Functions. 


Included Files, 
Definitions, and Types 


The most important thing 
to remember about 
thunking for the NetWare 
interfaces is to be sure that 
all addresses are passed as 
16-bit “selector:offset” 
addresses. 


Figure 27-3. Include 
Files for SAP 
Implementation. 


int main(void); 
int AdvertiseService(SAP_INFO *); 
void Sapper(SAP_INFO *); 


void ShutdownSap(SAP_INFO *); 


The include files needed for the source code can be found in Figure 27- 
3. Notice, that before you can include IPXCALLS.H, you need to define 
IS32BIT, and define the appropriate compiler (for the sample, we used 
BCPP), and include THUNK.H. With these steps taken, your 32-bit 
code will be able to make calls to the 16-bit IPXCALLS.DLL. See 
Appendix A for information on the specifics of modifying THUNK.H. 
The most important thing to remember about thunking for the NetWare 
interfaces is to be sure that all addresses are passed as 16-bit 
“selector:offset” addresses. IPXCALLS.DLL is a 16-bit system level 
driver and can only use 16-bit addresses. All pointers, both to code and 
to data, passed to any calls in this library must be cast to <type> NWPTR. 
This will force the compiler to generate code for pushing the 16-bit 
address on the stack. 


<stdia. n> 
CString. ir 
<errno.h> 
<stddef.h> 
<process.h> 
<dos. Nn? 


#tinclude 
#Hinclude 
#Hinclude 
#Hinclude 
#tinclude 
#include 
fHinclude <stdlib.h> 
fHinclude <alloc.h> 
fdefine IS32B1T 
4tdefine BCPP 
f#Hinclude <thunk.h> 
include <ipxcalls.h> 


/* 32-bit compile for “thunked” headers */ 
/* dating for Borland t+ *7 
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The constants used in the sample application are found in Figure 27-4. The 
first constant, SAP_INTERVAL_SECS is set to 60 seconds, the time 
required between SAP broadcasts. If an application broadcasts SAP pack- 
ets more often than this, it will cause unnecessary traffic on the network, 
taking bandwidth from other applications that need it. If the application 
broadcasts SAP packets less often than every 60 seconds, it will be aged out 
of the router’s server table on a regular basis. Being aged out of the router’s 
server table makes it difficult to locate the service on the network. 


#define SAP_INTERVAL_SECS 60 


#define PACKET_SIZE 576 
#define NO_MEMORY OxOOFF 
define MY_SERVICE OxXEEDI 
Figure 27-4. Constant #:define MY_SOCKET 0x5684 /* makes hi-lo 0x8456 */ 
Definitions. 
The PACKET_SIZE constant is defined to the packet size currently 
guaranteed to cross all NetWare routers. The MY_SERVICE constant is a 
define of a service type swapped to be stored in hi-lo (or big-endian) order. 
The MY_SOCKET constant is a define as the socket the service will listen 
for requests on. It is swapped to cause it to be stored in hi-lo order as well. 
The type definitions in the application—shown in Figure 27-5—are the 
packet data structure (SAP_DATA) and the set of information to be 
passed to the advertiser (SAP_INFO). These structures improve the 
ease-of-use for the code. 
typedef struct tSAP_DATA 
{ 
UINT16 sapPacketType; 
UINT16 servicelype; 
char serviceNameLl48]; 
UINT8 address[12]; 
UINT16 numNets; 
} SAP_DATA; 
typedef struct tSAP_INFO 
{ 
char serviceName[l48]; 
UINT16 servicelype; /* hi-lo */ 
Figure 27-5. UINT16 serviceSocket; /* hi-lo */ 
Structure Types 


Defined for Using } SAP_INFO; 
SAP. 
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main Function 


Figure 27-6. main 
Function. 


AdvertiseService 
Function 


The main function is the main thread of the code, and it is listed in 
Figure 27-6. It calls the initialization code, the deinitialization code, and 
the main processing functions. The initialization consists of setting up 
the service advertising information and calling the service advertising 
module, AdvertiseService. AdvertiseService will return the thread ID of 
the SAP thread. The main processing in the sample consist solely of a 
sleep function call that waits for a period of time that allows four SAP 
packets to be sent. Any processing that the application wants to do can 
be initiated in place of the sleep function. The deinitialization code 
consists of the call to ShutdownSAP. The AdvertiseService and the 
ShutdownSAP function calls are the core of the functionality for this 
sample program. You can call these two functions from any application 
that you want to use service advertising. 


int main() 
{ 


SAP_INFO sappy; 
int threadld; 


strcpy(sappy.serviceName, “MY_SERVER”); 
Sappy.servicelype = MY_SERVICE; 
Sappy.serviceSocket = MY_SOCKET; 


threadId = AdvertiseService(&sappy); 


if (threadId == -1) 
printf(“Error beginning advertising thread”); 


Sleep(SAP_INTERVAL_SECS*4) ; 
ShutdownSap(&sappy); 


return @: 


The AdvertiseService function is responsible for setting up the advertis- 
ing thread, and it is listed in Figure 27-7. By using a separate thread, 
your main program thread can continue processing without being 
blocked by the advertising. Having a separate function call to initialize 
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the thread for sending SAP broadcasts allows this code to be client 
platform independent. This same function could be moved to DOS, 
Windows, or Windows NT without an interface change. All the platform 
specific code is contained within the AdvertiseService call. 


/* This call should be the starting place of a thread */ 
int AdvertiseService(SAP_INFO *sapinfo) 
{ 

int threadId; 

void (*myThread)(void *); 


myThread = (void (*)(void *))Sapper; 


threadId = _beginthread(myThread, 4096, sapinfo); 
Figure 27-7, return threadId; 
AdvertiseService 
Function Call. 


The AdvertiseService function calls the _beginthread function. This 
function call takes three parameters: the address of the function the 
thread is to execute, the stack size for the thread, and the parameters to 
the function call. A pointer, myThread, of the type void (*)(void *) is 
declared and is set to the address of the Sapper function. The 
_beginthread function expects the first parameter to be of this type. To 
make the code clearer, the sample application uses a pointer rather 
than only typecasting the Sapper function in place. The stack size was 
set to 4096 bytes because the stack is allocated for threads in 4096 byte 
chunks. All of the SAP information necessary to describe a service is 
contained in the SAP_INFO structure. The address of this structure is 
passed as the final parameter to the _beginthread function. The threadId 
is the return value from this function. If the threadld is OxFFFF (1), 
then the advertising failed. 


SapperFunction The advertising itself takes place in the Sapper function, and it is listed 
in Figure 27-8. This module is where all interfacing to the network for 
SAP is located. The local variables consist of the event control block 
(ECB), the IPX Header, and the data portion of the packet. The Sapper 
function allocates an ECB and packet and then sets the ECB, header, 
and data pointers to the correct offsets in the allocated memory. For the 
details on using IPX in an application, refer back to the IPX and SPX 
chapters earlier in this book. 
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Figure 27-8. Sapper 
Function Call. 


int 


void 


OXFF, 


shutDown = FALSE; 


Sapper(SAP_INFO *sapinfo) 


IPX_ECB NWPTR ecb; 
IPX_HEADER NWPTR hdr; 


SAP_DATA NWPTR sap; 

UINT16 rcode; 

UINTS2 tt: 

UINT8 NWPTR tmp; 

UINT8 targetNodeLl2] = { 0x00,0x00,0x00,0x00, 


OXFF .OXPF, OXFF, OXFF,OxFF, 
0x04,0x52}; 


/* Allocate and set up ECB here */ 
ecb = (IPX_ECB NWPTR)malloc(sizeof(IPX_ECB)+PACKET_SIZE) ; 
if (ecb == NULL) 

return; 


ecb->fragCount = 2; 

ecb->dataLen = sizeof(IPX_HEADER) + sizeof (SAP_DATA); 
tmp = CUINTS NWPTR)Cecb+sizeor(IPX_ECB)); 

hdr (IPX_HEADER NWPTR)tmp; 

tmp += sizeof(IPX_HEADER) ; 

sap = (SAP_DATA NWPTR)tmp; 
ecb->fragListL0].fragAddress = hdr; 
ecb->fragListl0O].fragSize = sizeof(IPX_HEADER) ; 
ecb->fragListL1].fragAddress = sap; 
ecb->fragListLl].fragSize = sizeof(SAP_DATA): 
memcpy((UINT8 NWPTR)&(hdr->destNet), targetNode, 12); 
memset(ecb->immediateAddress, OxFF, 6); 
Sap->sapPacketlype = 2; 

Sap->servicelype = sapinfo->servicelype; 
Sstrcpy(sap->serviceName, sapinfo->serviceName) ; 
IpxGetInternetworkAddress(sap->address); 
memcpy(&(sap->address[10]), &(sapinfo->serviceSocket), 2); 
Sap->numNets = 1; 


/* Open a socket for serviceSocket */ 
rcode = Ipx0penSocket( 
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(UINT16 NWPTR *)&(Sapinfo->serviceSocket) ); 
if (rcode) 
goto Done; 


while (!shutDown) 
IpxSend(sapinfo->servicesocket, ecb); 
Sleep(SAP_INTERVAL_SECS) ; 

} 


/* free ECB here */ 


Done: 
free(ecb); 
Figure 27-8. Sapper _endthread(); 
Function Call. 
(Continued) 


In this example, the second fragment or portion of the packet is the 
SAP-specific portion of the packet. To identify that this is a SAP 
identification broadcast, sapPacketType is set to 2. Following the packet 
type, this packet describes the service and its location by using the 
service name, service type, and IPX address. The service type and 
socket that your application uses can be well-known, registered values. 
You can have these assigned to your company and application by calling 
Novell Developer Support. By registering your own socket and service 
type, you can guarantee that no one else uses those values for some- 
thing else, rendering your application unusable. 


You can get the network and node numbers by making a call to 
IpxGetInternetworkAddress. The last field set in the packet is the 
numNets field (which should not be confused with what you call your 
friends when they do stupid things). This field is the hop count to the 
service. The hop count represents how many routers away the service 
is from the network being broadcast to. In the case of a service 
advertising on its local net, this value is set to 1. When a router adver- 
tises server table updates on the networks it is connected to, it uses this 
same SAP structure to describe servers that are remote from it. This 
hop count can be as high as 16 before the routers will stop broadcasting 
information about the service. The function opens the service socket 
for the server application. All the requests for service will initially come 
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ShutdownSAP Function 





Figure 27-9. 
ShutdownSAP 
Function Call. 


in on this socket. The service can open another socket (preferably a 
dynamic one) for the application to call back on. This enables an 
application to always have a well-known socket to be contacted on, but 
allows each application to communicate with it on a separate socket. 


The Sapper function begins a “while” loop that is dependent on the 
global variable shutDown being set to FALSE. First the loop sends the 
SAP broadcast, then it sleeps for the SAP_INTERVAL. When it wakes 
up, the loop again checks the value of shutDown. When the shutDown 
value is set to TRUE, the advertising loop ends, the ECB and packet are 
freed, and the advertising thread ends. The shutDown flag is changed 
by the ShutdownSAP function. 


The last function call, the ShutdownSAP function, is found in Figure 
27-9. This function is called by the application when it is done servicing 
requests and is about to exit or shutdown services. This function has 
two specific tasks, to change the shutDown variable to TRUE and to 
send an advertising shutdown packet on the network. This function 
sets up the ECB to point to a packet that is identical to the one used to 
advertise the service in the first place. To shutdown a service, the 
numNets field in the SAP_DATA structure is set to 16. This value means 
that the server is shut down or is unreachable, which are logically the 
same situation. 


void ShutdownSap(SAP_INFO *sapinfo) 
{ 
IPX_ECB ecb; 
IPX_HEADER hdr; 
SAP_DATA sap; 
UINT16 rcode; 
UINTS2Z PEGs 
UINT8 targetNodeLl2] = { OxO00., 0X00 ,0x00, 0x00, 


OxFF, OxFF,OxXFF, OxXFF,OxFF. ORFF, 
0Ox04,0x52}: 


ecb.dataLen = sizeof(IPX_HEADER) + sizeof (SAP_DATA) ; 
ecb.fragCount = 2; 

ecb. fragListL0O].fragAddress = (void NWPTR)&hdr; 

ecb. fragListL0].fragSize = sizeof(IPX_HEADER); 

ecb. fragListLl].fragAddress = (void NWPTR)&sap; 
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ecb.fragListLl].fragSize = sizeof (SAP_DATA); 
memcpy(&(hdr.destNet), targetNode, 12); 
memset(ecb.immediateAddress, OXFF, 6); 
Sap.sapPacketlype = 2; 

Sap.servicelype = sSapinfo->servicelype; 
Sstrcpy(sap.serviceName, sapinfo->serviceName) ; 
IpxGetInternetworkAddress((UINT8 NWPTR)Sap.address); 
Sap.numNets = 16; 


ShutDown = TRUE; 
IpxSend(sapinfo->serviceSocket, (IPX_ECB NWPTR)&ecb) ; 


/* free ECB here */ 


Figure 27-9. IpxCloseSocket(sapinfo->serviceSocket) ; 
ShutdownSAP 
Function Call. 


(Continued) 
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For what can be more irrational than to take delight 1n many 
objects incapable of response... ? 


—Marcus Tullius Cicero, On Friendship 


Another call on the phone and a user can’t figure out why he can’t 
connect to the network. The phone rings, it’s your boss and he can’t 
remember which computers needed to have their video boards up- 
graded this month. Wouldn’t it be nice to turn to your computer and 
with a few simple choices in your management program be able to tell 
your boss which three machines still have monochrome adapters and to 
tell the first user that the router between his building and the next is 
down? Using NetWare diagnostics calls, you can create an application 
that can tell you just that kind of information and more. The requests 
listed in Figure 28-1 are just the beginning of what you can do with 
NetWare Diagnostic Services. These services are based on sending IPX 
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and SPX packets to NetWare servers and DOS, Windows, and OS/2 
clients on the network and querying them for information. In this 
chapter and the next, we will explain what information you can ask for 
and how to ask for it. 


Begin Diagnostics 

End Diagnostics 

Abort Sending Packets 

Get All Known Networks 

Get All Known Servers 

Get Bridge Driver Configuration 
Get Bridge Driver Status 

Get Bridge Driver Statistics 
Get Bridge Statistics 

Get Diagnostic Response 

Get Diagnostic Status 

Get GNMA Info* 

Get IPX/SPX Version 

Get IPX Statistics 

Get Local Tables 

Get LSL Configuration* 

Get LSL Statistics* 

Get Machine Dynamic Info* 

Get Machine Static Info* 

Get MLID Configuration* 

Get MLID List* 

Get MLID Statistics* 

Get NL Server Current State* 
Get NL Server Info* 

Get NL Server Stats* 

Get OS Version Info 

Get Primary Server Number 

Get Protocol Stack Configuration* 
Get Protocol Stack List* 

Get Protocol Stack Statistics* 
Get Remote SPX Socket 

Get Server Address Table 

Get Server Name Table 

Get Shell Address 

Get Shell Driver Configuration 
Get Shell Driver Statistics 
Get Shell Statistics 

Get Shell Version Info 


Figure 28-1. NetWare 
Diagnostics Services. 
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Figure 28-1. NetWare 
Diagnostics Services. 
(Continued) 





Get Specific Network Info 
Get Specific Server Info 

Get SPX Statistics 

Return Received Packet Count 
Send SPX Packet 

Start Counting Packets 

Start Sending Packets Timed 


* Calls supported by NetWare DOS Requester and Personal 
NetWare Server 





‘Mapping the Network 


Using IPX calls, an application can send queries to all the network 
addresses in a network, whether it is a single LAN or a large enterprise 
network. After the network map has been created, the application can 
create SPX connections with the individual nodes and query them for 
more information. Applications such as NetWare Care and NetMagic 
take advantage of these calls. 


The first step in creating the network map consists of sending a simple 
IPX-based diagnostic broadcast which allows you to create a list of all 
the nodes on the network. This diagnostic request is referred to as the 
configuration request packet. The structure of this packet is found in 
Figure 28-2. The packet is broadcast initially on the local network. The 
packet is broadcast to the diagnostic socket, opened as 0x5604 
(swapped), but the responses will return to whatever socket is in the 
source address of the IPX header. The responses from each node 
include information on which socket to use to connect to the node to 
retrieve more diagnostic information. The socket is followed by a 
component list that indicates which software components are loaded on 
the node and can be queried. The exclusion list allows you to reduce the 
number of duplicates you get as you make this broadcast several times 
to get a full list. (However, routers in the exclusion list will still respond; 
they cannot truly be excluded.) 
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Offset Item Size/Description 

Request: 

0 IPX Header 30 bytes 

30 Number Exclusion 1 byte (An exclusion 
Addresses address will reduce 


the number of 
duplicates) 


31 Exclusion Address List up to 80 6-byte node 
addresses 
Reply 
0 IPX header 30 bytes 
30 Diagnostics Major 
Version 1 byte 
31 Diagnostics Minor 
Version 1 byte 
32 SPX Diagnostic Socket 2 bytes 
34 Number of Components 1 byte 
35 ComponentsL[#components ] Variable 
Figure 28-2. 
Structure of the IPX 
Get Configuration 
Request and 
Response. 


Using the socket number and the source network and source node of 
the packet received, you can build a connection to each node that 
indicates it has arouting component. Making a series of inquiries to the 
routers for all the known networks, the IPX configuration request 
packet can then be broadcast throughout all the LANs in an 
internetwork configuration. Once you have a list of all the known 
networks and all the nodes on each of those nets, you can build a 
network map. An application that creates a map with the ability to 
retrieve all the information about a node becomes a good tool for 
remote administration. 


Once you have created a list of all the nodes on the network, you can 
query them to find out what information is available. This information 
can help you determine if the network is working reliably, if a segment 
of the network has become unreachable, if an individual workstation 
configuration is wrong, or if a particular LAN board has failed. The 
information gleaned from the queries to the network nodes can be used 
to create an optimal configuration of the network and to improve each 
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Figure 28-3. 
Component IDs and 
What Component 
They Identify. 


workstation or even the way individual software is implemented. You 
can use diagnostic services to extend the knowledge you have of what is 
going on in each individual workstation, or to improve the monitoring of 
your own application’s performance. 





Each network board on the network represents a network node. A 
network node can be a workstation, a file server, a printer, or some 
other piece of hardware that can communicate on the network. Each of 
these nodes has some set of network components installed and run- 
ning. When the nodes are queried with the IPX configuration request 
broadcast, they all return a component list of all the components for 
their node. The component structure returned indicates whether the 
node in question is a workstation, router, or server by what components 
are loaded. Some components are only found on a server and some 
components are only found on a workstation. This information then 
determines which queries can be made to the individual node. The 
possible components are listed in Figure 28-3. For example, you could 
query any node that had some type of router for All Known Networks. If 
the component list indicated the node had IPX/SPX loaded, you could 
query it for IPX or SPX statistical information. The available information 
can be used in for configuration tracking, diagnosing the efficiency of 
the network, or resource utilization. 


Component ID Component 


IPX/SPX 

Router LAN Driver (Bridge Driver) 
Shell LAN Driver (Shell Driver) 
Shel] 

VAP Shell 

Router (Bridge) 

File Server 

Non-dedicated IPX/SPX 

IPX Only (older versions of NetWare) 
DOS GNMA 

OS/2 GNMA 

Personal NetWare Server 


mer WO OND OP WPY Ff OC 


kr © 
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IPX/SPX Component 


Shell Component 


GNMA Component 


Router (Bridge) 
Component 


LAN Driver Component 


One of the components that can be found at most nodes on the network 
is the IPX and SPX component. On a DOS/Windows workstation, the 
SPX and diagnostic support is optional. If these modules weren't 
loaded, then you won’t have access to diagnostic queries. The IPX/SPX 
component information is of great use in the diagnosis of a slow or 
heavily used network or network segment. 


The shell component is the NetWare shell or requester running on the 
network node. It is responsible for the NetWare Core Protocol (NCP) 
communications to and from that node. This is the piece of software 
that maintains connections to the server, sends packets to and receives 
packets from the server, and works in conjunction with the workstation 
operating system to extend the local services to network access. 


The GNMA (Generic NetWare Management Agent) component is a 
piece of the client software with the NetWare DOS requester or the 
NetWare OS/2 requester. The GNMA component provides a hook for 
the requesters to return configuration and statistical information on the 
local workstation and requester. 


The router or bridge component is the software that allows packets to 
be routed between two network segments. This software is built in to 
NetWare file servers. With NetWare v2.x, it was also built in to the 
software used to create bridges. With Personal NetWare networks, a 
routing component can be loaded as a separate piece of software. 


The LAN driver component is present in workstation nodes and file 
server nodes. This piece of software is responsible for communicating 
information from the network to IPX. The LAN driver component in the 
ODI environment is referred to as a multiple LAN interface driver 
(MLID). These drivers communicate with IPX through the LSL. 


The MLID component is the ODI LAN driver software. The MLID is 
network board specific and responsible for the protocols necessary for 
the network board to send and receive packets on the network. 


376 OS/2 and NetWare Programming: Using the NetWare Client API for C 








Personal NetWare 
Server Component 


The LSL component is the software responsible for routing communica- 
tions between the MLIDs and the protocol stacks. The LSL also 
provides the ability to load processing stacks on the node that can 
perform a variety of functions including packet encryption and protocol 
translations. The LSL also provides a consistent interface to all PC 
hardware. 


The Personal NetWare server component is a peer server that can be 
installed at a workstation to share the resources of that workstation 
with other nodes on the network. If a workstation has a hard drive, a fax, 
or a printer, using Personal NetWare will allow it to share that resource 
with members of a workgroup. Personal NetWare also provides a low 
cost method of networking workstations directly without requiring a 
dedicated file server. 





NetWare Configuration Information 





A subset of the NetWare Diagnostic services are those calls that pro- 
vide you with network configuration information such as all the known 
networks, all the known servers, all the node addresses on the network, 
and the components running on the individual nodes. This information 
and the calls to gather it are the foundation of any application taking 
advantage of the NetWare Diagnostic Services. 


Once anode has responded to the IPX configuration request broadcast, 
an SPX connection can be established with the node and queries for 
local information can be sent. The component structure returned in 
response to the IPX configuration request will indicate which types of 
software are present at the node. The node could be a workstation, a file 
server, or arouter. The software installed could range from simply IPX 
to a full-blown file server. Other software that could be running on the 
node includes any diagnostic extension or a Personal NetWare Server. 
The workstation diagnostics will also indicate what workstation operat- 
ing system is running. 
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Software and 
Hardware Information 


Get IPX/SPX Version 


Figure 28-4. IPX/SPX 
Version Request and 
Reply. 


In addition to finding out what system software is running, the NetWare 
diagnostics calls also provide information on what versions are running. 
Using the appropriate calls, you can find out which version of client 
operating system is running, which IPX version is loaded, which SPX 
version is loaded, and which shell or requester is running. On a file 
server, you can discover the file server version and for NetWare 286, 
what VAP shell version is loaded. An individual application could also 
create its own diagnostic responder and respond to queries for software 
metrics. 


The Get IPX/SPX Version call will return the IPX major and minor 
version numbers and the SPX major and minor version numbers. Even 
data that seems fairly insignificant can tell you quite a bit about the 
workstation. If the IPX version is less than 3.10, then the workstation is 
not running Windows with NetWare. The minimum version of IPX that 
supported Windows is version 3.10. The structure of the packet re- 
turned by the “Get IPX/SPX Version” call is found in Figure 28-4. 


Offset Item Size/Description 

Request: 

0 SPX Header 42 bytes 

A? Component Number 1 byte (this field 1s 
from the 
configuration 
response) 

13 Request Type 1 byte (type = 0) 

Reply: 

0 SPX Header 42 bytes 

A? Completion Code 1 byte 

43 Interval Marker 4 bytes 

47 IPX Major Version 1 byte 

48 IPX Minor Version 1 byte 

49 SPX Major Version 1 byte 

50 SPX Minor Version 1 byte 
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Get Shell Version Into 


Figure 28-5. Shell 
Version Request and 
Reply. 


Get Machine Static Into 


Get Shell Version Info returns a small packet (Figure 28-5) containing 
the major and minor versions of the shell along with the revision 
number. This information can be useful for knowing if a node needs to 
be updated to a newer version of software or to trouble shoot problems 
that may be dependent on which version of the shell an application runs 
with. 


Offset Item Size/Description 
Request: 

0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type = 6 1 byte 
Reply: 

0 SPX Header 42 bytes 
A? Completion Code 1 byte 
43 Interval Marker 4 bytes 
47 Shell Major Version 1 byte 
48 Shell Minor Version 1 byte 
49 Shell revision level 1 byte 


The information from Get Machine Static Info provides hardware and 
software information from the workstation. This information (found in 
Figure 28-6) can help an administrator verify what hardware and operat- 
ing system software is installed at a network and even how much 
memory is available for use. With this ability to query individual work- 
stations, a network administrator could sit in his office and determine 
whether the hardware needed to be upgraded for a particular software 
upgrade. This information along with the information returned in Get 
Machine Dynamic Info will give you all the hardware and software 
configuration information available for a remote workstation without 
requiring you to ever leave your office. 


Managing Your Network Configuration Diagnostics 379 


Offset Item Size/Description 
Request: 
0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 
0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker 4 bytes 
47 Start Date 4 bytes 
ce! Start Time 4 bytes 
55 OS Major Version 1 byte 
56 OS Minor Version 1 byte 
57 OS Version Type 2 bytes 
59 Number of Serial Ports 1 byte 
60 Number of Parallel Ports 1 byte 
61 Floppy Drive Count 1 byte 
62 Floppy Drive Type 2 types 
64 Hard Drive Count 1 byte 
65 Keyboard Type 1 byte 
66 Boot Video Type 1 byte 
67 Display Memory 4 bytes 
71 Math Coprocessor 1 byte 
72 Coprocessor Type 1 byte 
is CPU Type 1 byte 
74 Reserved 1 byte 
iS Model Type 1 byte 
76 Serial Address 8 bytes 
84 Parallel Address 8 bytes 
92 Pointer Device 1 byte 
93 System Memory 2 bytes 
94 Memory Types 1 byte 
95 BIOS Type 1 byte 
96 BIOS Revision 2 bytes 
97 EISA MCA Slots 1 byte 
98 EISA MCA IRQ 16 bytes 
114 EISA Card Name 1 byte 
11S Bus Type 1 byte 
116 Hard Drive Type 4 bytes 
120 Memory Type Flag 1 byte 
121 Total XMS Memory 2 bytes 
123 Available XMS Memory 2 bytes 
125 Total EMS Memory 2 bytes 
Figure 28-6. Static 127 Available EMS Memory 2 bytes 
Machine Information 129 Reserved 22 bytes 


Request and Reply. 
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Get Machine Dynamic Get Machine Dynamic Info provides information on the values at a 
Info workstation that change or fluctuate. The date and time at the worksta- 
tion, information on removable drives, and mouse driver information 


Figure 28-7. Dynamic 
Machine Information 
Request and Reply. 


are returned in the packet found in Figure 28-7. 


Offset Item/Description Size 
Request: 

0 SPX Header 42 bytes 
A2 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 

0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker 4 bytes 
47 Current Date 4 bytes 
51 Current Time 4 bytes 
a Mouse Driver 1 byte 
56 Reserved 37 bytes 
93 Nonremoveable Drive Count 1 byte 
94 Nonremoveable Drive Drive Count 


StructureLDrive Count] 


Nonremoveable Drive Structure: 


= 15 


0 Drive Number 1 byte 
it Sectors Per Cluster 4 bytes 
5 Total Number of Clusters Per Drive 4 bytes 
9 Number of Available Clusters 4 bytes 
13 Bytes Per Sector 2 bytes 
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Get 0S Version Info 


Figure 28-8. 
Workstation OS 
Version Information 
Request and Reply. 


Get Local Tables 


The Get OS Version Info call returns the machine ID and operating 
system version strings for the workstation operating system. The 
operating system version strings are three strings that take up-to-41 
bytes. These strings are null terminated and are all in the version data 
packet defined in Figure 28-8. The three strings are the OS text string, 
the OS version text string, and the hardware type string. 


Offset Item/Description Size 
Request. 
0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type = 0 1 byte 
Reply: 
0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker 4 bytes 
47 Machine ID 1 byte 
48% OS Text (ASCIIZ string) variable 
2? OS Version Text (ASCIIZ 

string) variable 
ca Hardware Type Text 

(ASCIIZ string) variable 


*Total size of all three strings not to exceed 41 bytes 


The Get Local Tables function call returns the packet from Figure 28-9. 
The local tables are the list of physical and virtual LAN boards and their 
corresponding network numbers. An application should make this call 
to each node with a router (bridge) component. This information 
provides the addresses of the LANs attached to an individual machine 
that can be used to make diagnostics connections. Once the connection 
is establish, the Get Bridge Driver Configuration and Get Bridge Driver 
Statistics calls can be made to each address. 
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Figure 28-9. Router 
Local Tables Request 
and Reply. 


Get Bridge Driver 
Configuration and Get 


Shell Driver 
Configuration 


Offset Item/Description Size 

Request. 

0 SPX Header 42 bytes 

42 Component Number 1 byte 

43 Request Type = l 1 byte 

Reply: 

0 SPX Header 42 bytes 

42 Completion Code 1 byte 

43 Interval Marker 4 bytes 

47 Local Network Numbers[16] 64 bytes (4*16) 
ii 1* Local Node Addresses[16] 128 bytes (8*16) 


*Only the first 6 bytes of each entry is used 


The Get Bridge Driver Configuration call returns the non-ODI LAN 
driver configuration information from a NetWare file server or router 
(bridge). The Get Shell Driver Configuration call returns the non-ODI 
LAN driver configuration from a workstation. Both calls return the 
packet in Figure 28-10 with the appropriate fields set. Ifa field does not 
apply to a particular LAN driver, then it is set to -1. This packet contains 
the network and node address for the LAN board, the mode and con- 
figuration it is running in, the LAN board type, the version information, 
and the maximum data size supported. The maximum data size sup- 
ported will include the protocol headers. To know the maximum data 
that can be sent in a packet, the size of all the protocol headers must be 
subtracted from the maximum data size reported in this call. 
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Offset 
Request. 


0 
42 
43 


161 
163 
165 
16/7 
1&2 
172 
174 
Lez 
179 
180 
181 
182 
183 
184 
185 
186 


187 

Figure 28-10. LAN 188 
Driver Configuration 189 
Request and Reply. 
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Item/Description 


SPX Header 
Component Number 
Request Type = 0 


SPX Header 
Completion Code 
Interval Marker 
Network number 
Node Address 

LAN Mode 

Node Address Type 
Maximum Data Size 
Reserved 

LAN Hardware ID 
Transport Time 
Reserved 

Major Version 
Minor Version 


Ethernet Flag Bits 
Selected Configuration 


LAN Description 
IO Address 1 

IQ Decode Range l 
IO Address 2 

IO Decode Range 2 
Memory Address 1 


Memory Decode Range 1 


Memory Address 2 


Memory Decode Range 2 
Interrupt Is Used 1 


Interrupt Line l 


Interrupt Is Used 2 


Interrupt Line 2 
DMA Is Used 1 
DMA Line 1] 

DMA Is Used 2 
DMA Line 2 


Micro Channel Flag Bits 


Reserved 
Text Deseription 


Size 


42 bytes 
1 byte 
1 byte 


Get LSL Configuration 


Figure 28-11. LSL 
Configuration Request 


Get MLID List 


and Reply. 


The Get LSL Configuration function returns the information for the LSL 
component on anode. The LSL configuration information includes the 
LSL version information and the maximum number of LAN boards and 
protocol stacks the LSL is configured to support. The packet returned 
by this call is in Figure 28-11. 


Offset Item/Description Size 
Request. 

0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 

0 SPX Header 42 bytes 
A2 Completion Code 1 byte 
43 Interval Marker dword 

47 Config Major Version 1 byte 
48 Config Minor Version 1 byte 
49 Reserved DWORDL[ 2 ] 
a LSL Major Version 1 byte 
Bo LSL Minor Version 1 byte 
59 Maximum Number of Boards WORD 

61 Maximum Number of Stacks WORD 

63 Reserved BYTEELZ | 


The Get MLID List function will return a list of the ODI LAN drivers on 
the node being examined. This list is up to 20 entries in size and each 
entry is composed of an ID and a name. This list information can be 
used for making subsequent calls to Get MLID Configuration. The 
definition of the list packet is in Figure 28-12. 
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Offset 
Request. 


0 
A2 
43 


42 
43 
47 
48 


Item/Description 


SPX Header 
Component Number 
Request Type 


SPX Header 

Completion Code 
Interval Marker 
Number of MLIDs 
MLID ID ListlZ03 


MLID ID List Structure 


0 

2 
Figure 28-12. MLID 
List Request and 
Reply. 


Get MLID Configuration The Get MLID Configuration call returns the information for the ODI 
LAN driver on the node. The information is similar to the non-ODI LAN 
driver information, but has some information that is specific to ODI and 
ODI LAN drivers. This information includes the frame type, the look 
ahead size, and the best and worst data sizes. The packet returned by 


MLID ID 
Name 


this function is in Figure 28-13. 


Offset 
Request. 
0 

42 

43 


Figure 28-13. MLID 
Configuration Request 
and Reply. 
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Item/Description 


SPX Header 
Component Number 
Request Type 


SPX Header 

Completion Code 

Interval Marker 

Signature 

Config Table Major Version 
Config Table Minor Version 


Size 


42 bytes 
1 byte 
1 byte 


42 bytes 
1 byte 
dword 
1 byte 
byteL400] 


word 
byte[18] 


Size 


42 bytes 
1 byte 
1 byte 


42 bytes 
1 byte 
dword 
byteLl26] 
1 byte 
1 byte 


Figure 28-13. MLID 
Configuration Request 


and Reply. 
(Continued) 


75 

81 

83 

85 

87 

89 

9 

gs 

135 
145 
Ley 
189 
Lo 
193 
Lo? 
199 
201 
x 
209 
210 
211 
a 
rales 
219 
aa 
£23 
225 
eer 
meee, 
Zod 
ae bs 
rae Ys 
241 
les Bs 
254 
255 
256 
257 


Node Address 

Mode Flags 

Board Number 

Board Instance 
Maximum Packet Size 
Best Data Size 
Worst Data Size 

NIC Long Name 

NIC Short Name 
Frame Type String 
Reserved 

Frame Type ID 
Transport Time 
Source Route Handler 
Look Ahead Size 
Line Speed 

Queue Depth 
Reserved 

Driver Major Version 
Driver Minor Version 
Flags 

Send Retries 

Config Table Link 
Sharing Flags 

Slot 

IQ Address 1 

IO Range l 

IQ Address 2 

IO Range 2 

Memory Address 1 
Memory Size l 
Memory Address 2 
Memory Size 2 
Interrupt Line 1 
Interrupt Line 2 
DMA Line 1 

DMA Line 2 

Other Data 
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byte[6] 
word 
word 
word 
word 
word 
word 
byte[42] 
byte[10] 
byte[42] 
word 
word 
word 
dword 
word 
word 
word 
byte[6] 
1 byte 

1 byte 
byte[2] 
word 
dword 
byte[2] 
word 
word 
word 
word 
word 
dword 
word 
dword 
word 
byte 
byte 
byte 
byte 
byteL328] 


Get Protocol Stack List © The Get Protocol Stack List function will return a list of the protocol 
stacks loaded on the node being examined. This list is up to 20 entries 
in size and each entry is composed of an ID and a name. This list 
information can be used for making subsequent calls to Get Protocol 
Stack Configuration. The definition of the list packet is in Figure 28-14. 


Offset Item/Description Size 
Request. 
0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 
0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker dword 
47 Number of Protocol Stacks 1 byte 
48 Protocol Stack Structure[20] byteL20] * 20 
Protocol Stack Structure: 
Figure 28-14. Protocol Stack ID word 
Protocol Stack List 9 N byte lS) 
Structures. ae hs 
Get Protocol Stack The Get Protocol Stack Configuration call returns protocol stack name 
Confi ° and version information in the packet in Figure 28-15. This information 
ontiguration 
consists of text string names and the stack major and minor versions. 
Offset Item/Description Size 
Request. 
0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 
0 SPX Header 42 bytes 
42 Completion Code 1 byte 
Figure 28-15. 43 Interval Marker dword 
Protocol Stack 47 Config Major Version 1 byte 


Configuration Request AR 


and Reply. Config Minor Version 1 byte 
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49 Protocol Long Name byteLl42] 
91 Protocol Short Name byte[17] 
108 Stack Major Version 1 byte 
Figure 28-15. 109 Stack Minor Version 1 byte 
FT i pa 110 Reserved bytell6] 
and Reply. 
(Continued) 

Get NL Server Info The Personal NetWare Server provides extensive configuration and 
diagnostic information for the administrator as an aid in managing the 
peer server network. The configuration information can be retrieved 
using the Get NL Server Info function call. This call will return the 
packet from Figure 28-16. The major version, minor version, and beta 
versions are for the Personal NetWare server. The server name and 
workgroup name are those entered at installation of the Personal 
NetWare server. The remainder of the information deals with the 
configured and current resources used by the Personal NetWare server. 
Offset Item/Description Size 
Request. 

0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 
0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker dword 
47 Major Version 1 byte 
48 Minor Version 1 byte 
49 Beta Version 1 byte 
50 Server Name bytel48] 
98 Work Group Name byteL16] 
114 Work Group ID dword 
118 Rights Mask word 
120 Configuration Directory Buffers word 
122 Start Minutes 1 byte 
L23 Start Hours 1 byte 
124 Start Seconds 1 byte 
Figure 28-16. 125 Start Year (relative to 1980) word 
Personal NetWare 127 Start Day 1 byte 


Server Information 128 


Request and Reply. start Month I byte 
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Figure 28-16. 
Personal NetWare 
Server Information 
Request and Reply. 
(Continued) 


Operating System 

DOS Major Version 

DOS Minor Version 

Config Resources 

Current Resources 

Config Net Directories 
Current Net Directories 
Reserved 

Server Network Address 
Server Node Address 

Server Socket 

Reserved 

Is Share Loaded Flag 
Network Auditing Flag 
Allow Remote Management Flag 
Server Load Type 

Number of Responses Waiting 
Number of Receive Buffers 
Real Size Receive Buffer 
Reserved 

Size 10 Buffers 

Size Receive Buffers 
Configured Open Files 
Reserved 

Configured Client Tasks 
Reserved 

Number of IO Buffers 
Reserved 

Number ECBs Needing Buffer 
Configured Connections 
Reserved 

Configured Net Printers 
Current Net Printers 

Size of Print Buffers 
Reserved 

DOS Critical Section Count 


DOS Override Critical Section 


Reserved 

DOS Swap Data Size 
Reserved 

Swap Bytes if DOS Busy 
Swap Bytes Always 
Reserved 

Server TSR Size 
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1 byte 
1 byte 
1 byte 
word 
word 
word 
word 
word 
byte[4] 
byte[6] 
byte[2] 
word 
1 byte 
1 byte 
1 byte 
1 byte 
1 byte 
word 
word 
word 
word 
word 
word 
word 
word 
wordL3] 
word 
word 
1 byte 
word 
word[2] 
word 
1 byte 
word 
word 
word 
word 
dword 
word 
word[2] 
word 
word 
byte[12] 
word 


ERIE NB IS LETS ST FS EOS SE ETE] 


Get IPX Statistics 


Figure 28-17. IPX 
Statistics Request and 
Reply. 


In addition to all the configuration information, the diagnostic services 
can return statistical information relating to all the nodes and their 
components. This information can indicate the efficiency and reliability 
of the network. These statistics include good and bad packet counts, 
packet routing statistics, and local software processing information 
such as ECB availability and session listen information. 


The Get IPX Statistics call returns the information found in the packet 
in Figure 28-17. This information can provide you with insight on the 
reliability or level of use of the network segment the node resides on. It 
can also give you an idea as to whether your application is using enough 
ECBs. For example, if the getECBFailureCount increments quite a bit 
during a typical communications sequence, you know that you are 
using two few ECBs. You could get the statistics before you perform a 
typical sequence, perform the sequence, and then get the statistics 
again. If, prior to the communications sequence, the 
getECBFatlureCount was zero, then all the failures would likely be 
attributed to the application being tuned. Otherwise, a change in the 
ration of requests to failures would be attributable to the application 
being tuned. In the case of the IPX statistics, the malformed packet 
count can also be an indicator of an unreliable network. 


Offset Item/Description Size 
Request. 

0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type 1 byte 
Reply 

0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker dword 

47 Send Packet Count long 

51, Malformed Packet Count word 

53 Get ECB Request Count long 

5/ Get ECB Failure Count long 

61 AES Event Count long 

65 Postponed AES Event Count word 
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67 
69 


‘pt 

Figure 28-17. IPX 75 
Statistics Request and 717 
Reply. (Continued) 


Get SPX Statistics 


Max Configured Socket Count 
Open Socket Failure Count 
Listen ECB Count 

ECB Cancel Failure Count 
Find Route Failure Count 


word 
word 
long 
word 
word 


The SPX statistics (Figure 28-18) from the Get SPX Statistics call are 


good for monitoring the SPX communications on the network. If the 
bad packet counts are low, communications and applications are per- 
forming smoothly. If, however, these counts are high, either the net- 
work is not performing well or the individual applications are not using 


SPX correctly. 

Offset Item/Description 

Request. 

0 SPX Header 

A? Component Number 

43 Request Type 

Reply: 

0 SPX Header 

A? Completion Code 

43 Interval Marker 

47 Max Connections Count 

49 Max Used Connections Count 

51 Establish Connection Requests 
53 Establish Connection Failures 
af) Listen Connection Request Count 
57 Listen Connection Failure Count 
59 Send Packet Count 

63 Window Choke Count 

67 Bad Send Packet Count 

69 Send Failure Count 

rie Abort Connection Count 

i323 Listen Packet Count 

if Bad Listen Packet Count 

79 Incoming Packet Count 

83 Bad Incoming Packet Count 

85 Suppressed Packet Count 


Figure 28-18. SPX 97 
Statistics Request and 39 
Reply. 


No Session Listen ECB Count 
Watchdog Destroy Session Count 


Size 


42 bytes 
1 byte 
1 byte 


42 bytes 
1 byte 
dword 
word 
word 
word 
word 
word 
word 
long 
long 
word 
word 
word 
long 
word 
long 
word 
word 
word 
word 
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Get Primary Server 
Number 


Get Shell Address 


Get Server Address 
Table and Get Server 
Name Table 


Figure 28-19. Get 
Server Address Table 
and Get Server Name 

Table Requests and 
Replies. 


The Get Primary Server Number call returns the primary server num- 
ber from the node’s shell. The primary server number is the connection 
table number of the server from which the login script was executed. 
This server is typically the main working server for the individual 
logged in. 


The shell address returned by the Get Shell Address function call is the 
network, node, and socket of the IPX address which the node uses to 
communicate with file servers. The network and node numbers are 
those of the machine and the socket is a dynamic socket allocated by 
the shell from IPX. This socket is where all packets are received from 
the server. 


The Get Server Address Table provides the address table from the shell 
for the remote diagnostics application. Along with the server name 
table provided in the Get Server Name Table call, this enables the 
application to see which servers the node is logged in to along with their 
network addresses. If you are having troubles with communications 
between a server and a client, this information would allow you to seta 
point-to-point test between the two endpoints without creating a net- 
work map. The packets for these two calls are listed in Figure 28-19. 


Offset Item/Description 51ze 
Request. 

0 SPX Header 42 bytes 

A? Component Number 1 byte 

43 Request Type 1 byte 
Reply: 

0 SPX Header 42 bytes 

42 Completion Code 1 byte 

43 Interval Marker dword 

47 Address Table [8] 8 * size of 


Address Table Struct 
Address Table Structure: 
0 Server Used 1 byte 
l Order Number 1 byte 
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2 Server Network Number byte[4] 

6 Server Node Number byteL6] 

1? Server Socket Number word 

14 Received Time Qut word 

16 Immediate Node byte[6] 

22 Sequence Number 1 byte 

Z3 Connection Number 1 byte 

24 Maximum Time Out Value word 

26 Reserved byteL5] 

Request: 

0 SPX Header 42 bytes 

42 Component Number 1 byte 

43 Request Type 1 byte 

Reply: 

0 SPX Header 42 bytes 

42 Completion Code byte 
Figure 28-19. Get 43 Interval Marker dword 

Server Address Table Aq NanestS" byte[48] * 8 


and Get Server Name 
Table Requests and 
Replies. (Continued) 


Get Shell Statistics returns information pertaining to connections to 
servers, NCP processing, and network traffic. These counts are re- 
turned in the packet in Figure 28-20. The shellRequestsCount indicates 
how many NCP requests the shell has sent to servers. This value can be 
used with several of the other counts in the packet including 
timeoutsCount, writeErrorCount, invalidReplyHeaderCount, and 
invalidSequenceNumberCount to create ratios that can be used to com- 
pare the network reliability from day-to-day and configuration-to-con- 
figuration. Other counts that help gauge the network throughput or 
reliability, including the networkGoneCount, errorReceivingCount, and 
the allocateServerIsDownCount. 


Get Shell Statistics 
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Figure 28-20. Shell 
Statistics Request and 


Get GNMA Info 


Reply. 


Offset Item/Description Size 
Request. 

0 SPX Header 42 bytes 
A? Component Number 1 byte 
43 Request Type 1 byte 
Reply: 

0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker dword 
47 Shell Request Count long 
oul Operator Aborts Count word 
Se Operator Retries Count word 
ots) Timeouts Count word 
57 Write Error Count word 
59 Invalid Reply Header Count word 
61 Invalid Slot Count word 
63 Invalid Sequence Number Count word 
65 Error Receiving Count word 
6/7 No Router Found Count word 
69 Being Processed Count word 
v1 Unknown Error Count word 
73 Invalid Server Slot Count word 
fs Network Gone Count word 
i? Reserved word 
79 Allocate Cannot Find Route Count word 
81 Allocate No Slots Available Count word 
83 Allocate Server Is Down Count word 


The Get GNMA Info call provides version information on the Generic 
NetWare Management Agent (GNMA) and on the number of GNMA 
responders installed at the node (Figure 28-21). This version info and 
configuration info indicates what other information is available for an 
application to query. Each diagnostic responder will have its own 
information to provide that can be interpreted by an application aware of 
the packet packets used by the responder. 
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Offset Item/Description Size 

Request. 

0 SPX Header 42 bytes 

42 Component Number 1 byte 

43 Request Type 1 byte 

Reply: 

0 SPX Header 42 bytes 

A2 Completion Code 1 byte 

43 Interval Marker dword 

47 GNMA Major Version 1 byte 

48 GNMA Minor Version 1 byte 

AQ GNMA Number of Responders 1 byte 

50 Responder Type 

StructLl#responders ] byte[4] 

Responder Type Struct: 

0 Responder Type word 
Figure 28-21.GNMA 2 Responder Major Version 1 byte 
Information Request 

eS Responder Minor Version 1 byte 


and Reply. 


The Get Bridge Statistics function returns information pertaining to the 
routing of packets on the network. The packet structure is in Figure 
28-22. The tooManyHopsCount indicates how many packets were 
dropped because the hop count hit 16. If this count is high, the network 
should be monitored to discover the source of the packets. 
Reconfiguring the network segments can bring all the segments closer 
together to keep the hop count from being too high. If the 
noReceiveBuffersCount or the noSpaceForServiceCount are high, then 
the router’s buffers should be increased to allow better throughput on 
the network. The netBIOSPropogateCount is how many times a 
NetBIOS internet broadcast has been received and passed on by the 
router. The totalPacketsServiced and totalPacketsRouted counts indicate 
the efficiency of your network configuration. If a server is spending a 
large portion of the time routing packets rather than servicing them, 
then some clients on the same network segment as the router may have 
better performance if they are on a network segment with the server 
they use predominantly. 


Get Bridge Statistics 
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Figure 28-22. Bridge 
Statistics Request and 
Reply. 


Get All Known 
Networks and Get All 
Known Servers 


Offset Item/Description Size 
Request. 

0 SPX Header 42 bytes 
A2 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 

0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker dword 

47 Too Many Hops Count word 

AQ Unknown Network Count word 

51 No Space For Service Count word 

53 No Receive Buffers Count word 

55 Not My Network word 

5/7 NetBIOS Propagate Count long 

61 Total Packets Serviced Count long 

be Total Packets Routed long 


Using the information you receive from the Get All Known Networks 
call, you are able to continue the process of sending the configuration 
request packets to each of the networks. Using a combination of this 
information, you can create a network map indicating which nodes are 
connected to which networks. The packet returned from the Get All 
Known Networks call can hold up to 128 network numbers. In addition 
to this function, it is also useful to make the Get All Known Servers call. 
This function will return information on ten servers at atime. This call 
should be made several times indicating the number of servers to be 
skipped until no new servers are returned. Once the location and 
existence of the nodes on the network has been ascertained, the map 
can provide information as to what type of NetWare software is installed 
at the node. The packets these lists of information are returned in are in 
Figure 28-23. 
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Figure 28-23. 

All Known Networks 
and All Known 
Servers Requests and 
Replies. 


Offset 


Request. 


0 
42 
43 


42 
43 
47 
49 


Request: 


0 
42 
43 


A2 
43 
47 
49 


Server Info 


Item/Description 
Known Networks 


SPX Header 
Component Number 
Request Type 


SPX Header 

Completion Code 

Interval Marker 

Number of Network Addresses 
Address[128] 


Known Servers 


SPX Header 
Component Number 
Request Type 


SPX Header 

Completion Code 
Interval Marker 

Number of Servers 
Server Info Struct [10] 


Struct: 


Server Type 
Server Name 
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Size 


42 bytes 
1 byte 
1 byte 


42 bytes 
1 byte 
dword 
word 
byte[4] 


42 bytes 
1 byte 
1 byte 


42 bytes 
1 byte 
dword 
word 
byte[50] 


word 
byte[48] 





Get Specific Network 


Info 


Figure 28-24. Get 
Specific Network 
Request and Reply. 


The packet for the Get Specific Network Info function call (Figure 
28-24) contains information on how far the network is from the router 
being queried, how long it takes to route a packet to that network, and 
how many routes there are to that network. This is followed by a list of 
routes with the information on how far each route is from the network in 
question and what the address of the router is. 


Offset Item/Description Size 
Request. 
0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 
0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker dword 
47 Network Address byteL4] 
ae Hops To Net 1 byte 
of? Reserved byteL/] 
59 Route Time To Net word 
61 Number of Known Routers word 
63 Routing Info 

Structure[#routes ] byte[12] 
ROUTING Info StrUCcTUre: 
0 Router Forwarding Address byteLl6] 
6 Routing Board Number 1 byte 
7 Reserved byteL2] 
9 Route Hops 1 byte 
10 Route Time word 
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Get Specific Server Info 


Figure 28-25. Specific 
Server Information 
Request and Reply. 
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The Get Specific Server Info function gets information from router 
(bridge) component about a specific known server. This information 
(Figure 28-25) includes the type and name of the server, the address of 
the server, the distance the server is from the router, and a list of routes 
to the server. This information, along with that from the Get Specific 
Network Info function, is maintained in the servers routing tables in the 
same manner that it is returned to the workstation. Each call to Get 
Specific Network Info or to Get Specific Server Info returns one node 


from the routing table. 


Offset Item/Description Size 
Request. 

0 SPX Header 42 bytes 
A? Component Number 1 byte 
43 Request Type 1 byte 
Reply: 

0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker dword 

47 Server Type word 

49 Server Name byte[l48 ] 
97 Server Address byteL12] 
109 Hops To Server word 

Be Reserved byteL2] 
Lis Number of Routes word 

115 Route Source Infol[#routes ] byteL10] 
Route Source Info 

0 Route Source Address byteLl6] 
6 Route Hops To Source word 

8 Reserved word 





Get Bridge Driver 
Statistics and Get Shell 
Driver Statistics 


Figure 28-26. LAN 
Driver Statistics 
Request and Reply. 


The dedicated IPX LAN driver for the router or the shell will return 
statistics on packet transmission and reception. This information is 
returned from the Get Bridge Driver Statistics and Get Shell Driver 
Statistics calls. Additionally, there is space in the packet for the LAN 
board to return custom diagnostic information. The packet in Figure 
28-26 provides the driver and statistics versions as the first two fields. 
How well behaved the IPX and SPX applications running on the node is 
demonstrated by the packet counts for being too big or too small. The 
network reliability can often be gauged through examination of the 
retry count, the checksum error count, and the receiving mismatch 


count. 


OTT Set 
Request. 


0 
42 
43 


Item/Description 


SPX Header 
Component Number 
Request Type 


SPX Header 

Completion Code 

Interval Marker 

Driver Version 

Statistics Version 

Total Transmit Packet Count 
Total Receive Packet Count 

No ECB Available Count 

Packet Transmit Too Big Count 
Packet Transmit Too Small Count 
Packet Receive Overflow Count 
Packet Receive Too Big Count 
Packet Receive Too Small Count 
Packet Transmit Misc Error Count 
Packet Receive Misc Error Count 
Retry Transmit Count 

Checksum Error Count 

Hardware Receive Mismatch Count 
Number of Custom Variables 
Variable Data 


Size 


42 bytes 
1 byte 
1 byte 


42 bytes 
1 byte 
dword 
byte[2] 
byte[2] 
long 
long 
word 
word 
word 
word 
word 
word 
word 
word 
word 
word 
word 
word 
bytel495] 
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Get Bridge Driver 
Status 


Get NL Server Current 
State 


Figure 28-27. NL 
Server Current State 
Request and Reply. 


Get NL Server Stats 


The Get Bridge Driver Status call returns the status of the LAN boards 
in the router. For each board, the status could be alive and working, 
does not exist, or dead. This is useful information if a node is having 
trouble communicating to or through a router node. 


The Personal NetWare server’s current state information in Figure 
28-27 is returned by the Get NL Server Current State. This information 
profiles the server in terms of the numbers of connections, currently 
open files, current client task, free buffers, and semaphores. This 
information helps an administrator monitor how heavy the use of a 
particular Personal NetWare server becomes and take steps to mini- 
mize the impact of heavy access on the workstation user. 


Offset Item/Description Size 
Request. 

0 SPX Header 42 bytes 
A2 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 

0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker dword 

47 Current Connections word 

AQ Current Open Files word 

2 al Current Client Tasks word 

53 Current Number of Free Buffers word 

55 Current Number of Semaphores word 


The Get NL Server Stats function call returns the extensive statistics 
useful in profiling the peer server performance. These statistics are in 
the packet found in Figure 28-28. Information on how well the server is 
performing, how much throughput is occurring at the server, and how 
many errors are occurring is available. Repeated calls to this function 
could give an application the ability to graph the performance and 
fluctuation in server usage. 
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Offset Item/Description Size 
Request. 
0 SPX Header 42 bytes 
A? Component Number 1 byte 
43 Request Type 1 byte 
Reply: 
0 SPX Header 42 bytes 
42 Completion Code 1 byte 
43 Interval Marker dword 
47 Total Packets Received dword 
51 Bad Packets word 
53 Packets Not Processed 
Immediately word 
Bh Lost Responses word 
a7 Peak Connections Used word 
59 Peak Open Files word 
61 Peak Client Tasks word 
63 Watchdog Packets Sent word 
Gig Clients Watchdogged word 
67 ECB Reposts With No Buffers word 
69 Send Packet With ECB Active word 
71 Total SLIST Requests word 
73 Server Busy Packets word 
75 Server Busy Packets No Buffers word 
ii Unknown Requests word 
79 Write Behind Misses word 
81 Read Cache Hits dword 
85 Read Cache Misses dword 
89 Reads Too Large word 
91 CPiticd! Errors word 
93 Saved Large DOS Area dword 
97 Saved Small DOS Area dword 
101 Starvation Counter word 
103 Write Behind Hits word 
10S Cache Blocks in Use word 
107 Reserved dword 
Lil Packet Queue Runs dword 
Lis Idle Loop Wait Hits dword 
119 INT 21 Not Ours dword 
Figure 28-28. NL 123 Total INT 21 Calls dword 
Server Statistics LZ? Password Failures dword 
Request and Reply. 
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Get LSL Statistics, Get 
MLID Statistics, and 


Get Protocol Stack 


Statistics 


Figure 28-29. LSL 
Statistics Request and 
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Reply. 


Similar to the Get IPX Statistics, Get Bridge Driver Statistics, and Get 
Shell Driver Statistics calls but for the ODI world, the Get LSL Statis- 
tics, Get MLID Statistics, and Get Protocol Stack Statistics return the 
information found in the packets in Figures 28-29 through 28-31. This 
information can provide you with insight on the reliability or level of use 
of the network segment the node resides on. It can also give you an idea 
as to whether your application is using enough ECBs. For example, if 
the getECBFailureCount increments quite a bit during a typical commu- 
nications sequence, you know that you are using two few ECBs. You 
could get the statistics before you perform a typical sequence, perform 
the sequence, and then get the statistics again. If, prior to the commu- 
nications sequence, the getECBFailureCount was zero, then all the 
failures would likely be attributed to the application being tuned. Oth- 
erwise, a change in the ration of requests to failures would be attribut- 
able to the application being tuned. The checksumErrorCount can also 
be an indicator of an unreliable network. 


Offset Item/Description Size 
Request. 

0 SPX Header 42 bytes 
42 Component Number 1 byte 
43 Request Type 1 byte 
Reply: 

0 SPX Header 42 bytes 
A2 Completion Code 1 byte 
43 Interval Marker dword 

47 Statistics Major Version 1 byte 
48 Statistics Minor Version 1 byte 
49 Generic Counters word 

51 Valid Counters Mask dword 

a5 Total Transmit Packets dword 

59 Get ECB Requests dword 

63 Get ECB Failures dword 

67 AES Events Count dword 

fi Postponed Events dword 

IS Cancel AES Failures dword 

79 Reserved dword[2] 
87 Total Receive Packets dword 

91 Unclaimed Packets dword 

95 Other Data bytel480] 


Figure 28-30. MLID 
Statistics Request and 
Reply. 


Figure 28-31. 
Protocol Stack 
Statistics Request and 
Reply. 


Offset 
Request. 


0 
42 
43 


103 
107 


Offset 
Request. 


0 
42 
43 


Item/Description 


SPX Header 
Component Number 
Request Type 


SPX Header 
Completion Code 
Interval Marker 


Driver Statistics Major Version 
Driver Statistics Minor Version 


Number Generic Counters 
Valid Counters Mask 

Total Transmit Request 
Total Receive Request 

No ECB Available Count 

Too Big Transmit Request 
Too Small Transmit Request 
Receive Overflow Count 
Receive Too Big Count 
Receive Too Small Count 
Transmit Misc Count 
Receive Misc Count 
Transmit Retry count 
Receive Checksum Error Count 
Receive Mismatch Count 
Other Data 


Item/Description 


SPX Header 
Component Number 
Request Type 


SPX Header 
Completion Code 
Interval Marker 


Size 


Size 


42 bytes 
1 byte 
1 byte 


42 bytes 
1 byte 
dword 
1 byte 
1 byte 
word 
dword 
dword 
dword 
dword 
dword 
dword 
dword 
dword 
dword 
dword 
dword 
dword 
dword 
dword 
bytel468] 


42 bytes 


byte 
byte 


42 bytes 


byte 


dword 


statistics Major 
Statistics Minor 
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Version 
Version 


byte 
byte 


49 Generic Counters word 

51 Valid Counters Mask dword 

ao Total Transmit Packets dword 

59 Total Receive Packets dword 
Figure 28-31. 63 Ignored Receive Packets dword 
PACeCOl DCE. 55 Other Data byte[508] 


Statistics Request and 
Reply. (Continued) 


Testing the Network 





In addition to the information gathering available in the diagnostic 
services, network testing is possible. An application running on one 
workstation can create SPX diagnostic connections to two remote nodes 
and instruct them to send and receive messages between them. This is 
called point-to-point testing. Point-to-point testing will isolate problems 
on the network with communication between two points. These prob- 
lems could be caused by router problems, bad network boards, or 
heavy traffic. 


After connecting to the remote nodes, the diagnostic application will 
send a Start Counting Packets request to the receiving end. Then a 
Start Sending Packets request is sent to the transmitting node. This 
request specifies the number of packets to send to the other node. 
Once the specified number of packets is sent, data on the results of the 
sends including the number of transmission errors is returned to the 
diagnostic application. The application is then able to send a Return 
Received Packet Count request to the receiving end of the test. Ifthe 
number of packets transmitted and the number of packets received 
varies, then the route between the two end points is suspect. If the two 
endpoints are on the same local network, then the hardware in one or 
the other of the nodes or the hardware connecting the nodes is suspect. 
This test can begin with the two nodes that are having problems 
communicating and narrowed from each end to isolate the exact loca- 
tion of the problem on the network. 


Point-to-point testing is also useful in determining a network’s through- 
put. The instructions to the remote nodes in the test can be sent 
instructions that force them to send packets at higher and higher rates. 
The diagnostic application can then determine which rate of sends is 
the highest rate of reliable network throughput. 
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Application Algorithms 





Creating a map of the network is initiated by sending the IPX packet 
found in Figure 28-2. The packet is broadcast initially on the local 
network. After your map is created, you can start a iterative series of 
calls to each of the nodes in your list. You begin by creating an SPX 
connection to all the nodes that responded, using the socket specified 
in the response to the configuration request packet. Once the connec- 
tion is established, check the components from the component list. See 
Figure 28-32 for a list of steps to use in creating a network map. Each 
component has a set of calls that provide information pertaining to that 
component. Several calls are to be used in special situations. The calls 
and what they are used to do are discussed next. After that discussion 
are algorithms for using the other diagnostics calls. 


allocate and initialize an IPX Get Configuration Packet 

allocate and initialize the IPX Get Configuration Packet ECB 

allocate and initialize at least 2 IPX receive ECBs and packets 

set up a thread that will process the listen packets 

open a dynamic socket to receive the configuration responses on 

call IpxGetInternetworkAddress with the IPX header source 
address as the buffer 

set the source socket in the send ECB to the dynamic socket 
opened 


LOOP while component list includes router 


set up the destination address for a broadcast - 
the network number (0000 for the first packet), the node 
number (OXFFFFFFFF), and 
the socket (0x5604). 
send the request using IpxSendPacket. 
call IpxReceive on each receive ECB 
Save response information 
IF component list includes router 
call SpxEstablishConnection 


send GetLocalTables packet 
Figure 28-32. Steps 
for Gathering 
Information to Create 
a Network Map. 





Managing Your Network Configuration Diagnostics 407 


Begin Diagnostics 


End Diagnostics 


Get Diagnostic 
Response 


Get Diagnostic Status 


Get Remote SPX 
Socket 


Once you have received a response to the IPX Get Configuration Re- 
quest, you can create a diagnostic connection to the node that re- 
sponded. The SPX diagnostic socket from the response packet should 
be copied into an SPX header along with the network and node of the 
source address from the response packet header. Using this address, 
we send a connection request using SpxEstablishConnection. 


When the application is done using the diagnostic services, it must 
deinitialize by calling SpxTerminateConnection. This call requires the 
SPX connection ID from the call to SpxEstablishConnection. This step 
will then terminate the diagnostic SPX connection specified, release all 
allocated resources, and terminate diagnostics gracefully. 


If you create a custom diagnostic extension (diagnostic responder), the 
Get Diagnostic Response call can be used to send and receive the 
custom packets that you have designed. This call will use the same 
connection established by the Begin Diagnostics call. The first buffer is 
the request buffer and the second buffer is the reply buffer. 


The Get Diagnostic Status call is used in conjunction with the Get 
Diagnostic Response call. You make this call within a loop until the 
status returns as complete. At completion, the response buffer from Get 
Diagnostic Response will contain the response packet from the node 
being examined. 


If you have a network address for a node that you wish to perform a 
diagnostic call on, you can find out which socket to use to connect to the 
remote node to be examined. This connection can be used to query the 
node as well as to send it commands and instructions. 
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Configuration 
Information 


Figure 28-33. Steps 
for Making 
Configuration and 
Statistical Diagnostic 


Testing Cabling 


Queries. 


Once you have the address of a node, you can create a diagnostic 
connection to it by calling Begin Diagnostics with the address: the 
network, the node and the SPX diagnostic socket. Using the 
componentNumber returned in this packet, any diagnostic call can be 
made that applies to that component. For example, if the component is 
the router component, you would issue the Get Bridge Statistics to get 
statistical information. These steps are listed in Figure 28-33. 


complete steps in Figure 28-32. 
create SPX connection to node discovered using source 
address and SPX socket 
LOOP on number of component ids 


Switch component id 
query component 


call SpxTerminate connection 


Testing the cabling is accomplished through the point-to-point testing 
available in the diagnostic services. Using the information from IPX Get 
Configuration Request or two known network addresses, an application 
calls Begin Diagnostics to create a diagnostic connection to both remote 
nodes. Once the connections are established, one node is designated 
as the transmitting node and one node is designated as the receiving 
node. 


After connecting to the remote nodes, the diagnostic application will 
send a Start Counting Packets request to the receiving node. Then a 
Start Sending Packets request is sent to the transmitting node. This 
request specifies the number of packets to send to the other node. 
Once the specified number of packets is sent, data on the results of the 
sends including the number of transmission errors is returned to the 
diagnostic application. The application is then able to send a Return 
Received Packet Count request to the receiving end of the test. Ifthe 
number of packets transmitted and the number of packets received 
varies, then the route between the two end points is suspect. Ifthe two 
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endpoints are on the same local network, then the hardware in one or 
the other of the nodes or the hardware connecting the nodes is suspect. 
This test can begin with the two nodes that are having problems 
communicating and narrowed from each end to isolate the exact loca- 
tion of the problem on the network. The steps for this process are listed 
in Figure 28-34. 


complete steps in Figure 28-32 

create SPX connection with each of the nodes to be tested 

send a Start Counting Packets request to the destination 
node in the test 

set up the Send Packets request packet 

send a Start Sending PacketsTimed request to the source node 


. Pe toe 28-34. in the test 
Leche oe send a Return Received Packet Count to the destination node 


on the Network. 


The point-to-point testing process can also be used to check the net- 
work routing configuration. This test may fail due to one endpoint being 
too many hops from the other endpoint, an unreliable router at some 
location in the network route, or filtering NLMs installed on servers. 
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Ye even have shown me favor and good grace, 
I dare the more to ask of you a space 

Of audience, and to show you our request, 
Which ye shall deal with as ye think 1s best. 


—Geoffrey Chaucer, Canterbury Tales 


Being based on IPX and SPX, diagnostic services can be used by simply 
sending the right IPX or SPX packet. This is simplified through the use 
of the IPX/SPX Conn object described in the chapter “An IPX or SPX 
Protocol-based Service Provider” earlier in this book. The application 
discussed in this chapter uses that object and creates the necessary 
packets for sending diagnostic requests and receiving the responses. It 
is based on a C++ class, Conn, that we created to simplify the use of IPX 
and SPX. 
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The application is very simple, making only one IPX diagnostic request 
and one SPX diagnostic request. It consists of two functions, the main () 
function and the Diagnose() function. The main() function initializes 
and deinitializes the base Conn object and calls the Diagnose () function. 
The Diagnose () function creates and sends the diagnostic requests and 
receives and interprets the responses. 


The main() Function 





The main() function is the entry point into the application and the exit 
to the system. It initializes the global Conn object conn1. As seen in 
Figure 29-1, the object is initialized by passing the target address to 
communicate with, the socket to use, and the type of object (IPX or 
SPX: datagram or session support) to the object constructor. If the 
initialization is successful, then the main() function calls the Diag- 
nose() function. When the application is finished, the conn1 Conn 
object destructor is called. 





int main(void) 
{ 
// Set up to use IPX or SPX 


UINTI6 re; 
UINT8 targetL10] = {0x00,0x00,0x00,0x00, 
OxFF,OMFF .OxXFF, OxXFF ,OxFF,OxFFH: 
UINT16 sSocket=0x5604, rSocket=0x5555, 
SSocketS, rSocketS = 0; 
UINT32 status; 
Conn connl(target, &sSocket, &rSocket, &status, 
[PA OBW ) + 


UINT8 requestl546]; 

UINT8 replyL546], configReplyl546]; 
UINT32 requestSize, replySize; 

UINT8 componentID; 


i? (status) 
{ 
prineT ("Error Thitializing Conn. object: 
OxZx”, Status); 


connl.Conn: ¢~Conn() ; 
Figure 29-1. The return 0: 
main() Function for 
Initialization of 
DIAG.C. 
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Figure 29-2. The 
Diagnose () Function 
from DIAG.C. 


——— 


The two required steps demonstrated in this function involve the conn 1 
object. The conn1 object is an IPX object. This object will provide 
datagram communication with the endpoint specified by the target 
parameter in the constructor. To create a session object with this same 
target, specify another object with the same input parameters except 
the object type should be an SPX_OBJECT. The objects can be created 
in the main() function of the application or in any other module that 
makes sense. Creation of at least one object will verify whether the IPX/ 
SPX services are available to the application. 


The socket used to initialize the conn1 object is the well-known diagnos- 
tics socket. The diagnostic responders built in to the various types of 
NetWare nodes will be listening for communication on this socket. It 
will be used as the socket portion of the destination address for the IPX 
configuration request broadcast. 


The Diagnose() Function 





The Diagnose() function does the bulk of the work in the sample 
application, and it is listed in Figure 29-2. It creates the diagnostic 
packet for the configuration request broadcast, interprets the response, 
creates a session with a selected node, sends an SPX diagnostic query, 
and interprets that response as well. These are the basic steps you need 
to know to make any diagnostic query. 


// Send the IPX Configuration request packet (it’s only 
one byte long) 
requesri0d = Os 
connl.Conn::Send(request, 1); 
// Give enough time for a response. You may not need to 
// wait. It all depends on how slow/fast your network is. 
sleep(5); 
re = connl.Conn::Receive(configReply, PACKET_SIZE- 
sizeof(IPX_HEADER) ); 
if (re) 
{ 
connl.Conn::GetSource(target) ; 
printf(“\nResponse from: 
DXDKDXDX 2 BXOXBKBKOXBX 2 BKK” , 
targetLO], target[1], target[2], 
targetL3], targetl4], target[5], 
targetlL6], targetL7], target[8], 
targetL9], targetL10], target[1l]); 
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memcpy(&sSocketS, &configReply[2], 2); 


Conn conn2(target, &sSocketS, &rSocketS, 
&Status, SPX_OBJ); 
Switch (configReply[5]) 
{ 
case IPX_SPX_COMPONENT: 
requestid)] =.0; 
request[1] 
requestSize = 2; 
break; 
default: 
break; 


I 
oS 


// All the rest of the Diagnostics packets can be sent 
// the same way! 
// You need to check the errors coming back. 


re = conn2.Conn::Send(request, requestSize); 
1f €Fc) 
{ 
printt( “Error sending: Oxex", ro): 
goto done; 


re = connd.Gonn::Receive(reply, PACKET _SIZE- 
sizeof (IPX_HEADER) ); 
iT €re) 
{ 
printf(“Error receiving: OXEe” 4 fC) 
goto done; 
} 
Switch (configReply[l5]) 
{ 
case IPX_SPX_COMPONENT: 
printf(“\nRequest Completion Code = 
ox”, reply[0]); 


printf(“\nIPX Version: mU.6U”, 
replyls], 
replyl6]); 
printf(“\nSPX Version: HU. SU", 
replyl? ds 
replyl8]); 
break; 
default: 
Figure 29-2. The break : 
Diagnose() Function 
from DIAG.C. 
(Continued) 
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Configuration Request 
Broadcast 





Figure 29-3. Code 
Necessary to 
Broadcast to each 
LAN Segment for 
Configuration Info. 


Diagnostic Session 


The Configuration Request Broadcast is an IPX packet that consists of 
the header (taken care of by the conn1 object) and one byte of data set 
to zero. This data byte is the request number or function code. This 
packet is then broadcast to the network. At this point in the program, 
you could place the code from Figure 29-3 in a loop and send the packet 
to each different LAN segment you know of. You can discover lists of 
LAN segments by sending a Get All Known Networks query packet to a 
node that identifies itself as a bridge. This query would be an SPX query 
and needs to be set up in the way described in the next two sections. 


// Send the IPX Configuration request packet (it’s 

// only one byte long) 

requestlLQ] = 0: 

connl.Conn::Send(request, 1); 

// Give enough time for a response. You may not need 

// to wait. It all depends on how slow/fast your 

// network is. 

Sleep(5); 

rc = connl.Conn::Receive(configReply, 
PACKET_SIZE-sizeof(IPX_HEADER) ); 


The diagnostic session is an SPX connection between to machines that 
uses the SPX socket designated in the response to the configuration 
request packet. Using this socket, you create a connection to the remote 
machine that is dedicated to diagnostic queries and responses. With 
this session established, you can send any of the other diagnostic 
packets discussed in the last chapter. All of these packets consist of an 
SPX header (supplied by the Conn object) and the diagnostic portion of 
the packet supplied as the data. The packet data formats for the 
diagnostic portions of the packets are in the figures provided in the 
previous chapter. The code in Figure 29-4 indicates which code in the 
Diagnose() function actually sets up for the session. The first SendQ 
after this set up will initiate the connection and send the first diagnostic 
packet. As you can see from the figure, the socket to be used in the SPX 
session is pulled out of the configuration reply packet. This socket, 
along with the source net and node of the response packet, specifies the 
destination to be used to construct a new Conn object. This object is an 
SPX_OBJ and uses the target address we just built. 
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Figure 29-4. Code for 
Setting up a 
Diagnostic Session. 


SPX Diagnostic Queries 
and Responses 





connl.Conn::GetSource(target) ; 

printf(“\nResponse from: 4X4X4X4X i bXSXBXBXDXDK2DXOX” , 
targetL0O], targetLlJ, targetl2], target[3], 
targetl[4], target[5], targetl6], target[/7], 
targetL8], targetL9], targetl10], 
targetLill]); 

memcpy(&sSocketS, &configReply[2], 2); 


Conn conn2(target, &sSocketS, &rSocketS, &status, 
SPX_OBJ); 


The code in Figure 29-5 demonstrates how to send an SPX diagnostic 
query and receive its response. Using the configuration response, we 
can query any component on the specified node. To query each compo- 
nent, you must determine its offset in the list, which is the first item in 
the data portion of the diagnostic packet. The component list begins at 
offset five (5) in the configuration response, so subtracting five from 
where you are in the packet is a good way to get the offset value. 


After the component offset, you typically place the request code in the 
data of the query packet. The meaning of the request code is specific to 
the component. If a workstation has custom responders, the query 
code will need to understand the data the responder sends. 


The responses to the SPX diagnostic queries can be interpreted accord- 
ing to the response packet structures specified in the previous chapter 
with their corresponding queries. In the sample, we made an IPX/SPX 
version information request. The response to this request consists of 
the major and minor version values for IPX and SPX. The switch 
statements in the code give you a skeletal structure you can build all 
your variety of requests into. The code from Figure 29-5 could be placed 
in loop or a function call that is called for every node to get complete 
information for each one. 
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Switch (configReply[5]) 

case IPX_SPX_COMPONENT: 
request lO] = 0; 
requestL[1l] Os 
requestSize = 2; 
break; 

default: 
break; 


// All the rest of the Diagnostics packets can be 
// sent the 

// same way! 

// You need to check the errors coming back. 


re = conn2.Conn::Send(request, requestSize) ; 
1 47F¢) 


printf("Error sending: Ox%x”, rc); 
goto done; 


re = conn2.Conn::Receive(reply, 
PACKET_SIZE-sizeof( IPX_HEADER) ); 
a Gd 


Orintr( "Error recelyving: URPX 2 FE}: 
goto done; 
} 
Switch (configReply[5]) 
{ 
case IPX_SPX_COMPONENT: 
printf(“\nRequest Completion Code = %x” 
replylOd); 
DFINTTCNANIPA Version: 2uU.2u", replylsl, 
reply(6]); 
printf(“\nSPX Version: Z4u.%u”, replyl/7], 
replyledo; 
break; 


default: 
Figure 29-5. Sending break: 
and Receiving SPX 
Diagnostic Packets. 


All of the SPX diagnostic queries and responses are made in this way. 
Diagnostics can provide detailed information on each node in the net- 
work simply by sending IPX and SPX packets to query the nodes. 
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‘Little, brittle, network, fretwork... “ 


—Aristophanes, The Frogs 


Would you like to know the current memory or disk usage on your 
server? Or perhaps you need to know what NLMs are loaded on your 
NetWare v4.0 server? This information is referred to as part of the 
server environment. The server environment consists of the server 
hardware, the server software, and the state of the server. The most 
complete server environment information is available for NetWare v4.0. 
The calls found in Figure 30-1 are specific to NetWare v4.0. A set of 
information is available for NetWare v2.2 and NetWare v3.12 servers 
(Figure 30-2) with a separate set of information available for only 
NetWare v2.2 servers (found in Figure 30-3). 
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NWGetCachelInfo 
NWGetFileServerInfo 
NWGetNetWareFileSystemsInfo 
NWGetUserInfo 
NWGetPacketBurstInfo 
NWGetIPXSPXInfo 
NWGetGarbageCollectionInfo 
NWGetCPUInfo 
NWGetVolumeSwitchInfo 
NWGetNLMLoadedList 
NWGetNLMInfo 
NWGetDirCachelInfo 
NWGetOSVersionInfo 
NWGetActiveConnListBylType 
NWGetNLMsResourcelagList 
NWGetActiveLANBoardList 
NWGetLANConfigInfo 
NWGetLANCommonCountersInfo 
NWGetLANCustomCountersInfo 
NWGetLSLInfo 
NWGetLSLLogicalBoardStats 
NWGetMediaMgrObjInfo 
NWGetMediaMgrObjList 
NWGetMediaMgrObjChildrenList 
NWGetVolumeSegmentList 
NWGetVolumelInfoByLevel 
NWGetActiveProtocolStacks 
NWGetProtocolStackConfigInfo 
NWGetProtocolStackStatsInfo 
NWGetProtocolStackCustomInfo 
NWGetProtocolStkNumsByMediaNum 
NWGetProtocolStkNumsByLANBrdNum 
NWGetMediaNamebyMediaNum 
NWGetLoadedMediaNumList 
NWGetGeneralRouterAndSAPInfo 
NWGetNetworkRouterInfo 
NWGetNetworkRoutersInfo 
NWGetKnownNetworksInfo 
NWGetServerInfo 
NWGetServerSourcesInfo 
NWGetKnownServersInfo 

Figure 30-1. NetWare jy WGetServerSetCommandsInfo 


v4.x-specific Server 
Raoteaniment Sernces. NWGetServerSetCategories 
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Figure 30-2. Server 
Environment Services 
for NetWare v2.2 and 

v3.12. 





Figure 30-3. Server 
Environment Services 
for NetWare v2.2 
Only. 


NWCheckConsolePrivileges 
NWDownFileServer 
NWGetFileServerDateAndTime 
NWSetFileServerDateAndTime 
NWCheckNetWareVersion 
NWGetFileServerVersionInfo 
NWGetFileServerInformation 
NWGetFileServerExtendedInfo 
_NWGetFileServerlype 
NWGetFileServerLoginStatus 
NWGetFileServerName 
NWEnableFileServerLogin 
NWDisableFileServerLogin 
NWGetFileServerDescription 
NWGetFileServerVersion 
NWGetNetworkSerialNumber 
NWIsManager 


All of these calls to get this information are collectively referred to as 
the Server Environment Services. These services allow you to remotely 
query the server and get status information. This is especially useful if 
you keep your servers in secured or locked environments, or if an 
application requires a particular NLM loaded on the server, a particular 
version of the server, or a certain number of users on supported by the 
server. The information available from the MONITOR.NLM can be 
retrieved remotely by a supervisor or server console operator security 
equivalent. Changes to the server environment from a remote location 
are limited to prevent tampering with your servers. 


NWGetPhysicalDiskStats 
NWGetFileSystemStats 
NWGetDiskChannelStats 
NWGetDiskCacheStats 
NWGetFSDriveMapTable 
NWGetFSLANDriverConfigInfo 
NWGetFileServerLANIOStats 
NWIsManager 
NWGetFileServerMiscInfo 
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NetWare 2.x and VAPs 


Server Console 
Activities and 
Information 





NetWare v2.2 and v3.12 Support 


NetWare v2.2 servers use a different operating environment than 
NetWare v3.x servers and above. These differences result in different 
data being available to the network administrator. 


The NetWare v2.x environment consists of the NetWare operating 
system with limited extensibility provided by Value Added Processes or 
VAPs. The NetWare v2.x operating system has a less versatile file 
system than NetWare v3.x. The NetWare v2.x file system consists of 
volumes that cannot span more than one disk drive and Macintosh 
support built upon a shadow directory structure much like a bolt on 
system rather than truly integrated with the file system. Also not 
available are features like the OS/2 long name support and dynamically 
loadable modules, some of the extensible features found in NetWare 
v3.1x today. 


At the server, VAPs must be programmed according to rules much like 
those governing a good DOS Terminate and Stay Resident (TSR) pro- 
gram. They are written in assembly to be small and efficient. All 
resources such as memory must be allocated during initialization. To 
be loaded, VAPs must be in the SYS:SYSTEM directory on the server. 
VAPs do not run in a protection mode and can be hazardous to a server’s 
“up time” requirements (i.e. it could crash it). Novell has not actively 
upgraded or enhanced NetWare v2.x for several years, and has stopped 
selling it. This environment still exists at customer sites, but is being 
replaced by NetWare v3.x and v4.x servers. Some of the information 
relating to disk drives and volumes pertinent to NetWare v2.2 doesn’t 
apply to NetWare v3.1x servers. The set of information that applies to 
both NetWare v2.2 and NetWare v3.1x servers includes the server 
console information and the server configuration information. 


The Server Console activities and information consist of enabling and 
disabling logins, downing the file server, and checking for a 
connection’s console privileges as well as the file server date and time. 
These are the only console actions that can be taken on all versions of 
the NetWare operating system. When logins are disabled, the console 
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Server Configuration 
Information 


If the server supports long 
names as well as having a 
version of 3.11, it 1s also a 
1000-user version of the 
NetWare server. 


will send a broadcast message to all the current connections advising 
them that logging in to the server has been disabled. Once this 
message is sent, five minutes are allowed for the users to save their 
work and disconnect. At the end of the five minutes, the file server 
automatically disconnects all users except the supervisor or server 
console operator making the request. While logins are disabled, no one 
is able to create a connection to the server. 


Querying the server with the NWCheckConsolePrivileges call will return 
successfully if the connection is a console operator and will fail if the 
connection is for an object that isn’t a console operator. Console 
Operator is a group property of the server in the server’s bindery. 
Objects assigned to this group are allowed to access the server console 
information as well as to down the file server remotely. If the user isn’t 
a supervisor equivalent, then it must be a console operator to make 
many of the Server Environment Services function calls. 


Server Configuration Information consists of the version of the server, 
its revision, the services available and installed on the server, connec- 
tion status information, and the server name. The information available 
for the server configuration will tell you what versions and levels of 
TTS, accounting, bindery, QMS, and SFT support provided by the 
server. This information can be used to determine if features your 
application relies on in specific versions of these services. 


The server also supplies its version number and revision. If the version 
is 3.11 or higher and the maximum number of connections is greater 
than 250, then the server supports the set of QMS and connection calls 
that were modified for 1000-user NetWare systems. For more informa- 
tion on these changes, see the chapters on Queue Management Ser- 
vices and Connection Services earlier in this book 


Another way to find out if the server is a 1000-user server version of 3.11 
is to call NWGetServerType. This will return the type of server and the 
server version. Ifthe server supports long names as well as having a 
version of 3.11, it is also a 1000-user version of the NetWare server. 
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NetWare v2.x Server 
Device Information 





Server Information 


The NetWare v2.2 server devices can be queried for status and configu- 
ration information. This information applies primarily to the disk drives 
and the LAN cards. This LAN and disk configuration information 
includes what interrupts the cards are configured for and what memory 
resources they are using. The statistical information will include the 
number of packets dropped, the number of malformed packets, the 
number of disk cache misses, and the number of times the disk caches 
were flushed. This information can be valuable for writing an applica- 
tion that needs to profile resource utilization and error recovery for an 
environment that still uses NetWare 2 servers. One call, 
NWGetFileServerMisclInfo, is specific to NetWare v2.2. This call pro- 
vides information on the number of bindery objects and on the amount 
of dynamic memory used. 





NetWare 4 Support 


The NetWare v4.0 server included extensive new support for gathering 
information on the server remotely. The support included 43 new calls that 
describe all the modules, protocol stacks, routers, and media managers 
loaded on the file server. Full details on CPU, memory, and cache 
utilization were also provided. With the information provided about what is 
occurring at the NetWare v4.x server, it is easy to profile the load on the 
server and characterize how that load affects the CPU, cache, and memory 
pool. To determine the effect of an NLM on a server, you could have a 
program that queries the status of the memory and CPU before the NLM 
loads and then at defined periods after the NLM is loaded. With such 
profiling tools, network administrators would better be able to predict 
loading on servers and know when to add more servers to the network to 
maintain the desired data throughput. 


The server information (Figure 30-4) begins on the simplest level with 
the OS version information. Additionally, you can find out the server 
“set” commands and categories. If you write an NLM that will execute 
console commands sent to it, you could have complete remote control 
of your server. In order to maintain security, you would need to use 
some form of file system or NetWare Directory rights that could be 
verified before the console command was executed. 
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Figure 30-4. NetWare 
v4.x Server 
Information. 


If the ratio of NCP requests 
to the number of 
workstations 1s a high 
number, then the 
workstations are putting 
heavy demands on the 
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NWGetServerSetCommandsInfo 
NWGetServerSetCategories 
NWGetCachelInfo 
NWGetFileServerInfo 
NWGetNetWareFileSystemsInfo 
NWGetUserInfo 
NWGetPacketBurstInfo 
NWGetIPXSPXInfo 
NWGetGarbageCollectionInfo 
NWGetCPUInfo 
NWGetVolumeSwitchInfo 
NWGetDirCachelInfo 
NWGetOSVersionInfo 
NWGetActiveConnListByType 
NWGetVolumeSegmentList 
NWGetVolumeInfoByLevel 


You can profile the server usage with the file server information pro- 
vided which specifies the number of NCP requests processed, the 
number of NCP workstations, and “alloc” and “dealloc” information for 
dynamic resource usage. If the ratio of NCP requests to the number of 
workstations is a high number, then the workstations are putting heavy 
demands on the server resources. If the CPU utilization with these 
workstations connected is high, then an additional server could be 
added if more than one or two users are added, or the server hardware 
should be upgraded to a more powerful CPU. 


The cache information and the garbage collection information provides 
details on the memory usage at the server. This information can be 
used to determine whether the server has enough memory to operate 
efficiently for the demands placed on the server with the number of 
clients connected. The number and kind of client connections can be 
determined by getting the active connection list. Using these calls to 
take samplings of the server several times provides information for 
profiling the memory usage on the server. 


The packet burst and IPX/SPX calls can give you information on the 
reliability of your network and how much bandwidth is being used. The 
information returned by these calls largely consists of error counters. 
A small percentage of error in relation to the total number of packets is 
normal. As the error percentages increase, the network or the LAN 
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NLM Information 


Media Manager 
Information 


card on the server could be showing signs of wear or of exceeding its 
bandwidth. Additional tests could be performed on the network at this 
point. The diagnostics services used to monitor the network are dis- 
cussed in the Diagnostic Services chapters of this book. 


The load or demand for file services on the server can be monitored by 
using the volume information calls. This information provides details 
on how many reads and writes occur on the volume, how many of them 
are successful, and how many of them fail. 


NetWare Loadable Modules (NLMs) are software applications that can 
be loaded on NetWare 3 and NetWare 4 servers, to extend the services 
offered by those servers. Each of these modules uses resources pro- 
vided by the server. To manage the server and the resources available 
there, a network administrator can check what NLMs are loaded on 
each server by making the NWGetNLMLoadedList. This function can 
be called from an application to verify the existence of services (NLMs) 
the application requires. It returns a list of NLM numbers. These NLM 
Ids can be used to make subsequent calls to check on the resources of 
the NLM and to get version information and the file name and module 
name of the NLM. To manage a server or verify that an NLM is not out 
of control and consuming all the resources on the server, an application 
using the NWGetNLMsResourceTaglist can get a full list of all the 
resource tags in use by the NLM. Additionally, you can use the 
NWGetNLMInjo call to determine the version and revision level of any 
NLM in the NLM loaded list. 


New with NetWare 4 is the ability to have multiple types of media and to 
allow managers of these media to migrate high demand information to 
high speed media and low demand information to slower media. You 
accomplish this migration by running a media manager at the server 
that takes advantage of the data migration facilities built into the server. 
To find out what media managers are loaded on the server and get 
information on them, you can make calls to the server environment 
calls in Figure 30-5. These calls return lists of the media managers, their 
children, and the information on the particular media objects being 
managed. Storage Management Services (SMS), defined by Novell, 
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Figure 30-5. NetWare 
v4.0 Media Manager 
Function Calls. 


MLID and LSL 
Information 


Figure 30-6. NetWare 
v4.x LSL and LAN 
Configuration and 

Status Information. 


provide media management of objects such as tape drives and optical 
storage devices. Between SMS and data migration, the high speed 
media can be optimized to contain only the high demand, frequent 
access type of information. 


NWGetMediaMgrObjInfo 
NWGetMediaMgrObjList 
NWGetMediaMgrObjChildrenList 
NWGetMediaNamebyMediaNum 
NWGetLoadedMediaNumList 


The calls for the MLID and the LSL in the server environment services 
are found in Figure 30-6. The MLID and LSL modules on the server can 
be queried to determine the topology of the server and the network 
segments connected to it. Each MLID or LAN board driver also pro- 
vides configuration information and error counter information. The 
information provided for the LSL includes statistics for the logical 
boards and for information on the LSL itself. The logical board statis- 
tics can show you how many packets are being processed by each 
logical board. The LSL information will give you a good idea about what 
kind of behavior is occurring between the protocol stacks and the 
MLIDs. 


NWGetActiveLANBoardList 
NWGetLANConfigInfo 
NWGetLANCommonCountersInfo 
NWGetLANCustomCountersInfo 
NWGetLSLInfo 
NWGetLSLLogicalBoardStats 
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Protocol Stack You use the calls in Figure 30-7 to query the server for its Protocol Stack 
Information Information. Using these calls, you can determine which protocol stacks 
are loaded at the server and which of them are being actively used. Ifan 
individual protocol stack is not being accessed, you could unload it to 
Save memory on the server and let that memory be used more 
dynamically. Each protocol stack provides statistics and configuration 
information. This information should be interpreted according to the 
documentation from the providers of the protocol stacks. Protocol stack 
providers could also create configuration and management utilities 
using the information supplied by these function calls. 





NWGetActiveProtocolStacks 
NWGetProtocolStackConfigInfo 
NWGetProtocolStackStatsInfo 
NWGetProtocolStackCustomInfo 
Figure 30-7. NetWare = \WGetProtocolStkNumsByMediaNum 


iach euler aay NWGetProtocolStkNumsByLANBrdNum 


Router Information Each server also acts as a router for IPX and SPX packets on the 
network and as a service locator. To find out the information an 
individual server is maintaining on the routes and services in the net- 
work, you can make calls from the list in Figure 30-8. This information 
is maintained in the server RIP and SAP tables. In addition to the 
interfaces provided here to query the server, this information can be 
retrieved from the server using diagnostic services. 


NWGetGeneral RouterAndSAPInfo 
NWGetKnownNetworksInfo 
NWGetKnownServersInfo 
NWGetNetworkRouterInfo 


NWGetNetworkRoutersInfo 
Figure 30-8. NetWare NWGetServerInfo 
4.x Network and 


Service Information. NWGetServerSourcesInfo 


Several of the sets of calls found in the server environment services will 
need to make the calls in a specific order for the calls to succeed. The 
application in the next chapter will demonstrate which of these calls 
must be called first. 
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Thank Heaven, here ts not all the world. 


—Henry David Thoreau, Walden 


The server environment calls return information on the details of the 
environment established on the server due to the configuration and 
current utilization of the resources. The server environment consists of 
the server hardware, the server software, and the state of the server. 
Several of the sets of calls found in the server environment services will 
need to make the calls in a specific order for the calls to succeed. Our 
server environment application queries the server for several pieces of 
information. The function calls used to get this information are 
representative of the kind of information provided by the server 
environment services. For more details on the calls that can be made, 
check the discussions in the previous chapter. Each section references 
that calls that it applies to. 
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Different sets of APIs are available for different versions of NetWare 
servers. In order to make the proper calls to obtain the information you 
want from the server, you need to know what version of server you are 
communicating with. Additionally, in order to use these services, the 
user object must be a supervisor or console operator. NetWare servers 
provide this level of security to protect the information about how the 
server is configured and what resources are in use. The first two APIs 
that you need to use are NWCheckConsolePrivileges and 
NWGetFileServerInformation. How to make these calls is demonstrated 
in the code in Figure 31-1. 


int main(void) 
{ 


NWCONN_HANDLE conn; 
NWCCODE Pes 
BYTE majorVersion, 
minorVersion, 
dateTime[10]; 
FILESYS_StATS StatBuffer; 
NWFSE_VOLUME_SWITCH_INFO voliInfo; 
NWFSE_NLM_LOADED_LIST NLMList; 
NWFSE_NLM_INFO NLMInfo; 
NWFSE_ACTIVE_LAN_BOARD_LIST LANList; 
NWFSE_LSL_LOGICAL_BOARD_STATS boardStats; 
NWFSE_MEDIA_MGR_OBJ_LIST mediaMgrList; 
NWFSE_MEDIA_MGR_OBJ_INFO objinfo; 
NWFSE_ACTIVE_STACKS Stacks; 


NWFSE_PROTOCOL_STK_CONFIG_INFO StackInfo; 

NWFSE_GENERAL_ROUTER_SAP_INFO ripSapInfo; 

DWORD StartNum; 

char fileName[L15], name[48], 
copyright[256]; 


if (0 != (re = NWGetPrimaryConnectionID(& conn) )) 

{ 
printf(“\nNWGetPrimaryConnectionID: failed 4204x”, rc); 
exit(1); 

} 


if (NO CONSOLE_PRIVILEGES == 
NWCheckConsolePrivileges(conn) ) 
{ 
printf(“\nUnable to continue, no console privileges”); 
exit(1); 


Figure 31-1. Checking 


Console Privileges and } 
Server Version. 
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Figure 31-1. Checking 
Console Privileges 
and Server Version. 
(Continued) 


//Server Console Information 
if (0 != NWGetFileServerInformation(conn, NULL, & 
majorVersion, 
&minorVersion, NULL, NULL, NULL, 
NULL, NULL, NULL, NULL)) 


printf(“\nNWGetFileServerInformation: failed 204x”, rc); 
exit(1); 
} 
printf(“\n\nServer version: 4u:4u.”", majorVersion, 
minorVersion); 


NWCheckConsolePrivileges sends a packet to the server that verifies 
whether the user logged in is a console operator. If the user is not a 
console operator, all the server environment calls will return 
NO_CONSOLE_PRIVILEGES. The only parameter to this function call 
is the connection ID of the server to which the query should be sent. 


NWGetFileServerInformation sends a packet to the server to determine 
which versions of services are supported by the server. This is one call 
that allows your application to pass in NULL values for various param- 
eters to indicate which ones you don’t want returned. In this case, only 
the major and minor version variables are of interest for us to determine 
which server we are talking to. 


NetWare v2.2 and v3.12 Support 





NetWare v2.2 provided support for information concerning the physical 
devices on the server. Additionally, some logical information was 
available. This logical information was also provided in the NetWare 
v3.x servers, but the physical information was no longer available due to 
changes in the way NetWare 386 servers communicated with the hard- 
ware and the restructuring of the NetWare file system. The first func- 
tion call in Figure 31-2, NWGetFileServerDateAndTime, is supported on 
both NetWare v2.x and NetWare v3.x. The second function call, 
NWGetFileSystemStats, is specific to the NetWare v2.x file system. 
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if (majorVersion < 4) 

{ 
//NetWare v2.2 and v3.12 Support 
//Server Configuration Information 


rc = NWGetFileServerDateAndTime(conn, dateTlTime); 


printf(“\n\nDate: 4u\/4u\/4u, Time: 4u:%u”, 
datelimeLO], dateTime[l], 
datelime[L2], datelime[3], dateTime[4]); 


//NetWare v2.x Server Device Information 


re = NWGetFileSystemStats(conn, &statBuffer); 

printf(“\nMax Open Files: mu -\ 
\nCurrent Open Files: %u \ 
\nTotal Files Opened: %u”, 
StatBuffer.maxOpenFiles, 
StatBuffer.currOpenFiles, 
StatBuffer.totalFilesOpened) ; 


Figure 31-2. Getting 
the File Server Date 
and Time. 


NWGetFileServerDateAndTime returns the current date and time of the 

file server specified by the connection ID number that is passed into the 

consists of 7 bytes. function call as the first parameter. The date and time format consists 
of 7 bytes that are in the structure listed in Figure 31-3. 


The date and time format 
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Figure 31-3. Date and 
Time Buffer Structure. 


Server Information 









Day of the Week 0-6 (0=Sunday through 6=Saturday) 


NWGetFileSystemStats sends a request packet to the server specified by 
the connection ID number. The information returned is placed in the 
FILESYS_STATS buffer passed into the call. This structure includes 
information on the total number of files opened on the server, the 
maximum number of open files, and the current number of open files. 
Although this specific call is not available in NetWare v4.x, similar calls 
exist to report this information. 





NetWare 4.x Support — 


The NetWare v4.x support demonstrated in this application includes 
calls for configuration, version, and statistical information on several 
back-end services supported on the server. A full discussion of these 
calls and classifications is in the previous chapter. We will discuss the 
APIs called in this explanation in the order of server information, NLM 
information, media manager information, LSL and MLID information, 
protocol stack information, and router information. 


The first function call, NWGetVolumeSwitchInfo (Figure 31-4), is similar 
to the NWGetFileSystemStats call for NetWare 2. This call also returns 
the file open information as well as many other counters that pertain to 
all actions that can be taken on a directory entry in the file system. 
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These counters include opens, closes, reads, writes, renames, attribute 
queries and changes, trustee information queries and changes, etc. 
Most of the calls for logical file system information now function on a 
per volume basis rather than a system wide basis. This differs from 
NetWare 2 where all space limits and system counters were kept on a 
per file server basis. 


else 

{ 
//NetWare v4.0 Support 
//Server Information 
StartNum = 0; 


rc = NWGetVolumeSwitchInfo(conn, startNum, 
&volinfo); 
TT LC? 
printTc™\n\nError calling 
NWGetVolumeSwitchInfo: \ 
050%" » FE): 
else 
printr¢” \nTotal Files Opened: %U \ 
\nTotal Files Created: % U \ 
\nTotal Files Read: mu”, 
voliInfo.LFSCountersL4!, 
vollnfo.LFSCounters(5], 
volInfo.LFSCounters[0]); 


//NLM Information 
StartNum = 0; 


rc = NWGetNLMLoadedList(conn, startNum, NLMList); 
17 PG 
PrINntTC"\nWError calling 
NWGetNLMLoadedList: \ 
Uxax , Pel: 
else 


printf(“\n\nTotal number of NLMs loaded: 
HU”, 
NLMList.NLMsInList); 
printf(“\nGetting info on NLM #%u”, 
NLMList.NLMNums[0]); 


Figure 31-4. NetWare 
v4.0 Server rc = NWGetNLMInfo(conn, 
Environment Support. NLMList.NLMNums[O], 
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fileName, name, 
copyright, &NLMInfo); 
if (re) 
printfe"\nineError calling 
NWGetNLMInfo: \ 
OEEK" « PES 
else 
printf(“\nNLM name: oS \ 
\nNLM file name: 4s”, 
name, fileName); 


//Media Manager Information 
StartNum = 0; 
re = NWGetMediaMgrObjList(conn, startNum, 
FSE_MEDIA_OBJECT, &mediaMgrList); 
Ly ‘re 
pPrIAtTTC"\A\AERPOr calling 
NWGetMediaMgrObjList: \ 
OXRK” » PEI: 
else 


printf(“\n\nTotal number objects: oU”, 
mediaMgrList.objCount); 

printf(“\nInfo for object number: Zu”, 
mediaMgrList.objs[0]); 


re = NWGetMediaMgrObjInfo(conn, 
mediaMgrList.objs{[0], 
&objinfo); 
if (re) 
OFInET CO’ (A AErPor calling % 
NWGetMediaMgrObjInfo:\ \ Ox%x”, 


ro}: 
else 
printf(“\n\nMedia Type: mu”, 
objInfo.fseMMObjInfo.media- 
Type); 


//MLID and LSL Information 


Sstarthum = 0; 
Figure 31-4. NetWare rc = NWGetActiveLANBoardList(conn, startNum, 


v4.0 Server LANList); 
Environment Support. if (rc) 
(Continued) 
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OrintT¢” \Hinerror calling 
NWGetActiveLANBoardList:\ 
OMEK . FE} 
else 


printf(“\n\nTotal LAN boards: 4%u”, 
LANList.MaxNumOfLANs); 

printf(“\nGetting Stats for Board #%u”, 
LANList.boardNums[0]); 


rc = NWGetLSLLogicalBoardStats(conn, 
LANList.boardNums[0O], 
&boardStats); 
1? &Pe; | 
printtC"\nlneErroer calling \ 
NWGetLSLLogicalBoardStats: 
OxER, Pes: 


else 
printf(“\n\nTotal Transmitted: 
mU \ 
\nTotal Received: mu \ 
\nTotal Unclaimed: mu”, 


boardStats.LogItl1TxPackets, 
boardStats.LogIt|]RxPackets, 
boardStats.LogUnclaimed- 
Packets); 

} 

//Protocol Stack Information 

SstartNum = 0; 

re = NWGetActiveProtocolStacks(conn, startNum, 


&stacks); 
17 (Fe) 
printf(“\n\nError in NWGetActiveProtocol - 
sbacks: \ GREK", FED? 
else 
{ 
printf(“\n\nNumber Active Stacks: hu”, 


stacks.stackCount): 
printf(“\nInformation for Stack#: %u”, 
stacks.stackInfo[l0].StackNum) ; 


re = NWGetProtocolStackConfigInfo(conn, 
Stacks.stackInfoL0O].StackNum, 
Figure 31-4. NetWare name, stackInfo); 
v4.0 Server if (rc) 


Environment Support. 
(Continued) 
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Figure 31-4. NetWare 
v4.0 Server 
Environment Support. 
(Continued) 


NLM Information 


OPTALT CO VAARErPor calling 


NWGetProtocolStackConfigInfo: \ Ox%x”, rc); 
else 
{ 
printf(“\n\nStack Name: aS” 
name) ; 


printt(*\nStack Version: %u.%u", 
StackInfo.stackMajorVersionNum, 


StackInfo.stackMinorVersionNum): 
} 


//Router Information 
StackNum = Q; 
re = NWGetGeneralRouterAndSAPInfo(conn, 
&ripSapInfo); 
17 APC) 
printTC™r’ninerror calling \ 
NWGetGeneralRouterAndSAPInfo:  \ 
DRBM y TER 
else 
printf(“\nInternal RIP Socket: Ox%x”, 
ripSapInfo.internalRIPSocket) ; 


The second functional group demonstrated in Figure 31-4 is the NLM 
information from the server. To get any NLM information from the 
server, you have to make the NWGetNLMLoadedList first to get a list of 
the NLM ID numbers. With these numbers, you can get information for 
any of the NLMs in the list. The next call you see in the sample is the 
call to the NWGetNLMInfo API. This call expects the connection ID 
number you used in the NWGetNLMLoadedList call and the NLM 
number returned in that list. The NWGetNLMInfo call returns to you 
the NLM file name string, NLM name string, copyright string, and a 
structure containing more detailed information about the make up of 
the NLM. This information will allow you to determine which NLMs 
are loaded and what versions. Additionally, this tells you which lan- 
guage the NLM is using for messages, how much memory is available, 
and how many external symbols are referenced by the NLM. 
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Media Manager 
Information 


LSL and MLID 
Information 


The third functional group demonstrated in Figure 31-4 is the media 
manager information for the server. To get any media object informa- 
tion from the server, you have to make the NWGetMediaMgrObjList 
first to get a list of the object IDs. Using these object IDs, you can make 
other media manager information calls to get detailed information on 
the types of media on the server, their configuration, and their status. 
The call the sample uses next is NWGetMediaMgrObjInfo. The informa- 
tion returned from this call includes the media type, capacity, block 
size, status, and control information. The media can be hard disks, 
CDs, WORMs, tapes, or magneto-optical drives. Using this group can 
enable you to profile the storage and backup capabilities of each server 
queried. You are also able to determine the current status of any of the 
media. This status will include feedback on whether the object is 
currently remirroring. 


The fourth functional group demonstrated in Figure 31-4 is the LSL and 
MLID information for the server. To get any MLID information from 
the server, you have to make the NWGetActiveLANBoardList first to get 
a list of the LAN cards available. Using the board numbers returned in 
this list, you can make calls to get information about that board’s 
configuration and statistical information. 


The statistical information on the LAN boards includes information on 
the total packets received, the total packets transmitted, and the num- 
ber of packets received but not claimed by any applications. Other 
statistics include the number of the different kinds of errors that can 
occur in an MLID, like packet buffers that are too small, packets that 
are too large, packets that are too small, and a lack of ECBs for packets 
received. The configuration information for an MLID includes informa- 
tion on which memory addresses and IRQs it uses, the maximum 
packet size it can transmit, and which slot the card is in on the server. 
Additionally, custom information can be provided by the LAN cards that 
can be interpreted by the application according to the vendor’s specifi- 
cation. 


~ Asmall management application could be built by a LAN card manufac- 


turer. This application could interpret the custom information and 
enable network administrators to improve the LAN card’s performance. 
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Protocol Stack 
Information 


Router Information 





The LSL configuration and statistical information includes information 
on the number of MLIDs and protocol stacks loaded. The statistics 
include information on the number and type of errors that occur during 
the processing of packets between the LAN media and the protocol 
stacks. 


The fifth functional group demonstrated in Figure 31-4 is the protocol 
stack information for the server. To get any protocol stack information 
from the server, first you make the NWGetActiveProtocolStacks call. 
This call gives you a list of protocol stack numbers and short names. 
The short names allow you to determine the type of stack loaded 
without making extra calls to the server for additional information. If 
the protocol stack is one you are interested in displaying information 
for, you can make additional calls using the stack number to specify 
which stack is of interest. The statistical information includes the 
number of packets sent, the number of packets received, and the 
number of packets ignored. Additionally, you can query the protocol 
stack for custom information according to its specification. 


The sixth and final functional group demonstrated in Figure 31-4 is the 
router information for the server. You can query for all the known 
routes to a specific network and how far the destination is from the 
server you are communicating with. You can also get information on 
the servers including their names, their addresses, and the number of 
hops they are from the server you are querying. This is one method of 
querying the server for all of its routing information. Another method is 
discussed in the diagnostics section. 


Applications using these server environment services can profile server 
usage and highlight possible problems in the server configuration. The 
amount of memory on the server, the configuration of its storage and 
network media, and the number of errors occurring on the network will 
all aid network administrators in improving the number and configura- 
tion of the servers provided on their networks. Additional work could 
be done in an application to display the information graphically to allow 
administrators the opportunity maintain a finger on the pulse of the 
network operating system. 
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All the DLLs and header files shipped in the NetWare Client SDK for C 
were developed in a 16-bit environment. In order for 32-bit compilers to 
“thunk” properly (i.e. call 16-bit interfaces from 32-bit code) certain 
changes must be made to the header files to tell the compiler that the 
interfaces are 16-bit. 


A set of header files was uploaded to the NetWare Developers’ Forum 
on CompuServe. At press time the zip file that contained the thunked 
headers is called HCSDK5.ZIP. These header files were modified to 
allow for code and data pointers to be defined as __far16 for Borland and 
as _Seg16 and _Far16 for C Set/2. As is always the case with software 
development there were bugs. The first section details the bugs in the 
thunking headers and the changes that need to be made to use these 
headers. The second section of this appendix lists the steps necessary 
to change the headers you received with the retail versions of the SDK 
to thunk properly. If you change your own headers, you will also need 
to create a THUNK.H header file. The information you need to make 
these changes for Borland C++ are in Figure A-1. 


44] 


ifndef IS32BIT 
+#define IS1L6BIT 


fFelse 


define INT16 short 
define INT32 int 
define NWFAR far 


fedefine NWPTR __farl6 * 
#tdefine NWAPI __farl6 __pascal 
f#Fdefine NWPASCAL __pascal 


Figure A-1.  #define NWAPIPTR __farl6 __pascal * 
Information for Handa? 


Creating a Thunk 
Header. 


Notice, that before you include the headers for the SDK, you need to 
add #define IS32BIT, and a #define for the appropriate compiler (for the 
sample, we used BCPP), and then include THUNK.H by adding the line 
#include <thunk.h>. The most important thing to remember about 
thunking for the NetWare interfaces is to be sure that all addresses are 
passed as 16-bit selector:offset addresses. The prototypes in the header 
files will enable the compiler to know when to generate the necessary 
code for converting 32-bit flat addresses to 16-bit selector offset ad- 
dresses. Some variables will need to be cast to the appropriate types in 
order to avoid compiler warnings and errors. 


Fixes to the Header Files from HCSDK5.ZIP 





You will want to make the following fixes to the “thunked” header files 
provided by Novell developer support. Be careful, though, about adding 
a new line to the file where you are required to “insert” something. It 
may throw off the line number reference we’re giving you. As a general 
rule, just put the new line in the existing space between sections. 
(“Remarking” out a line to preserve its original form and then inserting 
a changed line where you’re required to “change” a line could also 
throw off the line numbering.) 
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1. THUNK.H 


Insert this line after line 54: 

#tdefine NWAPIPTR _Farl6 _Cdecl _loadds * 
This line after line 61: 

define NWAPIPTR __farl6 __cdecl * 
And this line after line 68: 


define NWAPIPTR __farl6 __cdecl * 
2. NWDSDSA.H 


1. Change line 127 from this: 

char NWFAR *destRDN 
to this: 

char NWPTR destRDN 
2. Change the int on line 169 to int16 

3. NWDSFILT.H 

Change lines 103, 111, and 117 from this: 

void (NWPTR freeVal)(uint32 syntax, void NWPTR val) 
to this: 

void (NWAPIPTR freeVal)(uint32 syntax, void NWPTR val) 


4, IPXCALLS.H and SPXCALLS.H 


1. Before the function prototypes in both files, add this: 


#ifdef _ cplusplus 
extern “C” { 
dFendif 


2. After the function prototypes in both files, add this: 
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ifdef __ cplusplus 
fendi f 


In the SPXCALLS.H file, don’t put this at the end of the file; 
it needs to come before the last #endif in the SPXCALLS.H 
file. 


3. Search and replace the following in both files: 


change UCHAR to UINTS8 
change USHORT tO UINT16 
change ULONG to UINT32 


0. NWLOCALE.H 


1. Move line 1 to a location after the comments and make it look 
like this by adding only the second line: 


ifndef _ NWLOCALE_H_._ 
tKdefine __NWLOCALE_H__ 


2. Beginning with: #1fndef NWAPI, delete 16 lines, to line 
26 or 27 just before NUMBER_TYPE long double. 


3. Change this line: 
typedef unsigned int size_t; 
to this line: 
typedef unsigned short size_t; 


4, Change the prototypes for Nwprintf, Nwsprintf, and Nwvprintf 
to look like these: 


extern INT16 __farl6 __cdecl Nwprintf(char NWPTR 
format, «..J; 

extern INT16 __farl6 __cdecl Nwsprintf(char NWPTR 
butter, char NWPIR format,... 23 

extern INT16 NWAPI Nwvprintf(char NWPTR format, 
void NWPTR arglist); 


5. Now, delete the second to last line that looks like this: 


#Fdefine _ NWLOCALE_H__ 
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6. Search and replace all occurrences of int with INT16 
7. Change this line: 


int far cdecl NWwsprintf ( 
char NWPTR buffer, 
char NWPTR format, 
oe 
to this: 
ifdef NWWIN 
int far cdecl Nwwsprintf ( 
char NWPTR buffer, 
char NWPTR format, 
swat 
dFendi f 
6. NWDSBUFT.H 
Change this line: 
Size_t size, 
to this: 


intl6o size, 


7. NWDSMISC.H 
Change the int on line 120 to an int16 


8. UNICODE.H 


Change the definition of size_t to: 


typedef unsigned short size_t 
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Fixes to the Header Files from the CD-ROM 





Version of the SDK 


We strongly recommend that you make changes to the header files in 
HCSDK5.ZIP. However, if you do not have access to this file, then here 
is a list of all the things you'll need to change in the CD-ROM version of 
the SDK. However, these changes are so extensive, we cannot guaran- 
tee your header files will correctly even if you make all these changes. 
(Nor can we guarantee that we’ve covered everything.) 


NWFAR NWPASCAL NWAPI 
NWFAR * 
















HSEM void NWPTR 





Figure A-2. 
Replacement Table for 
Thunking Header 
files. 
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1. Modify all headers according to Figure A-2. 
2. All NWDS*.H headers 
Change the int16 return codes to NWDSCCODE 
3. NWDSTYPES.H 
Replace the non-Macintosh definition section with: 
f#Finclude <nwcaldef.h> 


4. NWCALDEF.H 


Add: 
#defineuint32 UINT32 
4#defineuintl6 UINT16 
#defineuint8 UINT8 
4#defineint32 INT32 
f#tdefineintl6 INT16 
#defineint8 INT8 

5. NWDSFILT.H 
Change the prototypes: 


void NWAPI NWDSFreeFilter(Filter_Cursor_T NWPTR cur, 
void (NWPTR freeVal)(uint32 syntax, void NWPTR Wald} 


NWDSCCODE NWAPI NWDSPutFilter( NWDSContextHandle 

context, Buf_T NWPTR buf, Filter_Cursor_T NWPTR 
cur, void (NWPTR freeVal)(uint32 syntax, void NWPTR val) 
NWDSCCODE NWAPI NWDSDelFilterToken(Filter_Cursor_T 
NWPTR cur, void (NWPTR freeVal)(uint32 syntax, void 
NWPTR val)); 


to: 


void NWAPI NWDSFreeFilter(Filter_Cursor_T NWPTR cur, 

void (NWAPIPTR freeVal)(uint32 syntax, void NWPTR 

val)); 

NWDSCCODE NWAPI NWDSPutFilter( NWDSContextHandle 
context, Buf_T NWPTR buf, Filter_Cursor_T NWPTR 

cur, void (NWAPIPTR freeVal)(uint32 Syntax, void 

NWPTR val) 
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NWDSCCODE NWAPI NWDSDelFilterToken(Filter_Cursor_T 
NWPTR cur, (NWAPIPTR freeVal)(uint32 syntax, void 
NWPTR Valdis 


6. NWLOCALE.H 
Make the same changes as in Section 1. 
7. IPXCALLS.H and SPXCALLS.H 
Add: 
#include <nwcaldef.h> 


8. Make all changes from section 1 
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NWGetProtocolStackConfigInfo, 420, 428, 436, 437 
NWGetProtocolStackCustomInfo, 420, 428 
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NwGetVolumeStats, 223, 242 
NWGetVolumeSwitchInfo, 420, 425, 433, 434 
NWGetXXxTableHandle, 96 
NWIncrement, 81 
NWiInitAuditFileRead, 202, 213, 215 
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NWLoginToFileServer, 175, 177, 180 
NWLogoutAsVolumeAuditor, 198, 215 
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